OpenAPI Framework Core

Common errors

• TypeError: Cannot read properties of undefined (reading 'initialize')

  cause The `.initialize()` method was called on an `undefined` or improperly constructed `OpenApiFramework` instance, often due to forgetting `new` or incorrect asynchronous handling.
  fix Ensure `OpenApiFramework` is correctly instantiated with `new OpenApiFramework(args)` before calling `.initialize()`, and remember to `await` the `initialize()` method as it returns a Promise. Example: `const api = await new OpenApiFramework(args).initialize();`

• Error: OpenAPI validation error: '...path/to/field...' is not a valid OpenAPI 3.0.0 spec

  cause The `apiDoc` object provided to the `OpenApiFramework` constructor contains structural or semantic errors that prevent it from conforming to the OpenAPI 3.0.0 specification.
  fix Thoroughly review your `apiDoc` object against the official OpenAPI 3.0.0 specification. Utilize online OpenAPI validators or IDE plugins to lint and identify specific schema violations.

• Error: Missing or invalid 'paths' configuration in OpenApiFramework arguments.

  cause The `paths` property within the `OpenApiFramework` constructor arguments is either absent, empty, or not in the expected array format, preventing the framework from discovering operation handlers.
  fix Provide an array for the `paths` property in your `OpenApiFramework` configuration, typically containing file paths or objects that define your API operations. If no specific paths are needed for a basic setup, explicitly provide an empty array: `paths: []`.

Warnings

• gotcha Prior to version 0.8.0, the `express-openapi-validation` dependency, often used by framework integrations, had a bug where it modified parameters, causing non-idempotent behavior. This could lead to inconsistent request processing.
  Fix: Upgrade `openapi-framework` and any dependent framework-specific packages (e.g., `express-openapi`) to version 0.8.0 or higher to ensure parameter processing is idempotent and consistent.
• breaking Version 0.7.0 introduced several vendor extensions (e.g., `x-express-openapi-disable-middleware`, `x-express-openapi-disable-coercion-middleware`) allowing explicit control over middleware execution. Existing configurations might implicitly rely on previously enabled middleware, which could now be disabled by default or require explicit re-enabling.
  Fix: Review your OpenAPI specification and framework configuration to explicitly set these vendor extensions as needed. Ensure that critical middleware (like validation or coercion) is enabled if your application depends on it.
• gotcha Versions 0.9.0 and 0.9.1 introduced vendor extensions (`x-express-openapi-additional-middleware` and `x-express-openapi-inherit-additional-middleware`) for defining and controlling scoped middleware inheritance. While powerful, misconfiguration can lead to middleware not being applied as expected or unexpected inheritance behavior.
  Fix: Use `x-express-openapi-additional-middleware` at the path or operation level in your OpenAPI specification to apply custom middleware. For precise control over inheritance, set `x-express-openapi-inherit-additional-middleware: false` where you need to prevent parent-scoped middleware from applying.

Install

• npm install openapi-framework npm
• yarn add openapi-framework yarn
• pnpm add openapi-framework pnpm

Imports

• OpenApiFramework
  wrong:

  const OpenApiFramework = require('openapi-framework');

  correct:

  import { OpenApiFramework } from 'openapi-framework';

  Primary class for initializing the OpenAPI framework. Supports ESM and ships TypeScript types.
• IOpenApiFrameworkArgs

  import type { IOpenApiFrameworkArgs } from 'openapi-framework';

  Type definition for the constructor arguments of OpenApiFramework, useful for TypeScript users, ensuring correct configuration structure.
• OpenApiFramework.initialize

  const api = await new OpenApiFramework(args).initialize();

  The `.initialize()` method is asynchronous and returns the initialized API instance, which includes the processed `apiDoc`. It became available and returned an initialized API from v0.8.0.

Quickstart

Demonstrates the basic initialization of the OpenApiFramework with a simple OpenAPI 3.0 specification. It illustrates how to instantiate the framework with an `apiDoc` and call its asynchronous `initialize()` method to prepare the API definition. This core setup is then consumed by framework-specific adapters.

import { OpenApiFramework } from 'openapi-framework';

const apiDoc = {
  openapi: '3.0.0',
  info: {
    title: 'Example API',
    version: '1.0.0',
  },
  paths: {
    '/status': {
      get: {
        summary: 'Get API status',
        responses: {
          '200': {
            description: 'API is healthy',
            content: {
              'application/json': {
                schema: {
                  type: 'object',
                  properties: {
                    status: { type: 'string', example: 'ok' }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  components: {},
};

async function setupOpenApi() {
  const framework = new OpenApiFramework({
    apiDoc: apiDoc,
    paths: [
      // In a real application, this would point to directories
      // containing operation handlers or provide a mechanism to load them.
      // For this example, we simulate an empty but valid configuration.
    ],
    logger: console, // Or a custom logger implementation
  });

  const initializedApi = await framework.initialize();
  console.log('OpenAPI Framework initialized successfully.');
  // In a full application, 'initializedApi' would then be used
  // by a specific web framework integration (e.g., express-openapi)
  // to mount routes and apply OpenAPI middleware.
}

setupOpenApi().catch(console.error);