Registry / web-framework / openapi-framework

openapi-framework

library12.1.3jsnpmunverified

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.

web-framework http-networking serialization

npm install openapi-framework

github ↗package ↗

INSTALL

IMPORT

SIG · OPENAPI-FRAMEWORK

openapi-framework

web-frameworkjavascriptv12.1.3

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

OpenApiFramework

✓ import { OpenApiFramework } from 'openapi-framework';

✗ const OpenApiFramework = require('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.

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);

Debug

Known issues

gotchaPrior 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.

affects: <0.8.0

breakingVersion 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.

affects: >=0.7.0

gotchaVersions 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.

affects: >=0.9.0

Errors

Common errors & fixes

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

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

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.

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: []`.

Upgrade

Version history

12.1.3latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/kogosoftwarellc/open-api ↗

packagehttps://www.npmjs.com/package/openapi-framework ↗