{"id":11495,"library":"openapi-framework","title":"OpenAPI Framework Core","description":"openapi-framework is a foundational Node.js library designed to integrate OpenAPI (formerly Swagger) specifications with various web frameworks. It abstracts away the complexities of OpenAPI specification parsing, routing, and validation, providing a flexible, framework-agnostic interface. This allows higher-level packages, such as `express-openapi` or `koa-openapi`, to build robust API servers by utilizing its core engine. The package is currently at version 12.1.3, indicating a mature and actively maintained codebase, though specific recent release cadences are not provided in the excerpt. Its primary differentiator lies in offering a reusable core for OpenAPI integration, enabling developers to adopt standard API documentation and validation patterns without being tied to a specific web server implementation.","status":"active","version":"12.1.3","language":"javascript","source_language":"en","source_url":"https://github.com/kogosoftwarellc/open-api/tree/master/packages/openapi-framework","tags":["javascript","openapi","swagger","framework","typescript"],"install":[{"cmd":"npm install openapi-framework","lang":"bash","label":"npm"},{"cmd":"yarn add openapi-framework","lang":"bash","label":"yarn"},{"cmd":"pnpm add openapi-framework","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Primary class for initializing the OpenAPI framework. Supports ESM and ships TypeScript types.","wrong":"const OpenApiFramework = require('openapi-framework');","symbol":"OpenApiFramework","correct":"import { OpenApiFramework } from 'openapi-framework';"},{"note":"Type definition for the constructor arguments of OpenApiFramework, useful for TypeScript users, ensuring correct configuration structure.","symbol":"IOpenApiFrameworkArgs","correct":"import type { IOpenApiFrameworkArgs } from 'openapi-framework';"},{"note":"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.","symbol":"OpenApiFramework.initialize","correct":"const api = await new OpenApiFramework(args).initialize();"}],"quickstart":{"code":"import { OpenApiFramework } from 'openapi-framework';\n\nconst apiDoc = {\n  openapi: '3.0.0',\n  info: {\n    title: 'Example API',\n    version: '1.0.0',\n  },\n  paths: {\n    '/status': {\n      get: {\n        summary: 'Get API status',\n        responses: {\n          '200': {\n            description: 'API is healthy',\n            content: {\n              'application/json': {\n                schema: {\n                  type: 'object',\n                  properties: {\n                    status: { type: 'string', example: 'ok' }\n                  }\n                }\n              }\n            }\n          }\n        }\n      }\n    }\n  },\n  components: {},\n};\n\nasync function setupOpenApi() {\n  const framework = new OpenApiFramework({\n    apiDoc: apiDoc,\n    paths: [\n      // In a real application, this would point to directories\n      // containing operation handlers or provide a mechanism to load them.\n      // For this example, we simulate an empty but valid configuration.\n    ],\n    logger: console, // Or a custom logger implementation\n  });\n\n  const initializedApi = await framework.initialize();\n  console.log('OpenAPI Framework initialized successfully.');\n  // In a full application, 'initializedApi' would then be used\n  // by a specific web framework integration (e.g., express-openapi)\n  // to mount routes and apply OpenAPI middleware.\n}\n\nsetupOpenApi().catch(console.error);","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"<0.8.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=0.7.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.9.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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();`","cause":"The `.initialize()` method was called on an `undefined` or improperly constructed `OpenApiFramework` instance, often due to forgetting `new` or incorrect asynchronous handling.","error":"TypeError: Cannot read properties of undefined (reading 'initialize')"},{"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.","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.","error":"Error: OpenAPI validation error: '...path/to/field...' is not a valid OpenAPI 3.0.0 spec"},{"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: []`.","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.","error":"Error: Missing or invalid 'paths' configuration in OpenApiFramework arguments."}],"ecosystem":"npm"}