{"id":14567,"library":"express-openapi","title":"Express OpenAPI Framework","description":"express-openapi is an unopinionated framework designed to integrate OpenAPI (formerly Swagger) specifications into Express.js applications. It currently supports OpenAPI versions 2.0 and 3.0. The library prioritizes performance and extensive testing, aiming to keep development as close to native Express patterns as possible while providing robust API documentation and validation capabilities. It achieves its features, such as parameter defaults, type coercion, request/response validation, and security handling, by leveraging a suite of modular `openapi-*` packages. The current stable version is 12.1.3. While not explicitly stating a release cadence, its version history suggests active development. Key differentiators include its flexible, unobtrusive design, comprehensive middleware configuration via vendor extensions, and the ability to maintain API documentation in sync with application code.","status":"active","version":"12.1.3","language":"javascript","source_language":"en","source_url":"https://github.com/kogosoftwarellc/open-api/tree/master/packages/express-openapi","tags":["javascript","openapi","swagger","express","typescript"],"install":[{"cmd":"npm install express-openapi","lang":"bash","label":"npm"},{"cmd":"yarn add express-openapi","lang":"bash","label":"yarn"},{"cmd":"pnpm add express-openapi","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"JSON schema validation.","package":"ajv","optional":false},{"reason":"Adds common formats for AJV validation.","package":"ajv-formats","optional":false},{"reason":"Adds custom keywords for AJV validation.","package":"ajv-keywords","optional":false},{"reason":"HTTP error creation.","package":"http-errors","optional":false},{"reason":"Path matching for Express routes. (Important for Express 5 breaking changes).","package":"path-to-regexp","optional":false},{"reason":"Express-compatible router utility.","package":"router","optional":false},{"reason":"Serving static files, often for Swagger UI.","package":"serve-static","optional":false},{"reason":"Parsing and dereferencing OpenAPI documents.","package":"swagger-parser","optional":false}],"imports":[{"note":"The primary function to initialize the OpenAPI framework with your Express app. Prefer ES Modules import style.","wrong":"const openapi = require('express-openapi');\nconst initialize = openapi.initialize;","symbol":"initialize","correct":"import { initialize } from 'express-openapi';"},{"note":"Type import for the initialized OpenAPI application instance, useful for TypeScript projects.","symbol":"OpenApiApp","correct":"import type { OpenApiApp } from 'express-openapi';"}],"quickstart":{"code":"import express from 'express';\nimport { initialize } from 'express-openapi';\nimport * as swaggerUi from 'swagger-ui-express';\n\nconst app = express();\nconst PORT = process.env.PORT ?? 3000;\n\n// Basic API Document - OpenAPI 3.0\nconst apiDoc = {\n  openapi: '3.0.0',\n  info: {\n    title: 'My Simple API',\n    version: '1.0.0',\n    description: 'A simple API with Express and OpenAPI'\n  },\n  paths: {\n    '/hello': {\n      get: {\n        summary: 'Responds with a greeting',\n        responses: {\n          '200': {\n            description: 'Successful response',\n            content: {\n              'application/json': {\n                schema: {\n                  type: 'object',\n                  properties: {\n                    message: { type: 'string' }\n                  }\n                }\n              }\n            }\n          }\n        }\n      }\n    }\n  }\n};\n\n// Create a dummy 'operations' object for the path handler\nconst operations = {\n  get: (req: express.Request, res: express.Response) => {\n    res.status(200).json({ message: 'Hello, OpenAPI!' });\n  }\n};\n\ninitialize({\n  app,\n  apiDoc,\n  paths: [\n    {\n      path: '/hello',\n      module: operations\n    }\n  ],\n  docsPath: '/api-docs' // Path where Swagger UI will be served\n});\n\n// Serve Swagger UI\napp.use('/api-docs', swaggerUi.serve, swaggerUi.setup(apiDoc as swaggerUi.JsonObject));\n\n// Start the Express server\napp.listen(PORT, () => {\n  console.log(`Server listening on port ${PORT}`);\n  console.log(`Swagger UI available at http://localhost:${PORT}/api-docs`);\n  console.log(`API endpoint at http://localhost:${PORT}/hello`);\n});\n","lang":"typescript","description":"Sets up an Express server, initializes `express-openapi` with an in-memory OpenAPI 3.0 specification, defines a simple '/hello' endpoint, and serves Swagger UI for API exploration. This demonstrates basic setup, routing, and documentation generation."},"warnings":[{"fix":"Review Express 5 migration guides, especially for route definitions and regular expressions. Test thoroughly after upgrading Express. Ensure `path-to-regexp` is compatible or consider pinning its version if issues arise.","message":"Express.js 5 introduces significant changes to path matching via `path-to-regexp` (v8.x vs v0.x), which `express-openapi` relies on. Migrating an Express 4 application to Express 5 might cause unexpected routing behavior or `SyntaxError: Invalid regular expression` if path patterns are not updated.","severity":"breaking","affected_versions":">=10.0.0"},{"fix":"If encountering `SyntaxError: Invalid regular expression` related to route paths, explicitly pin the `glob` dependency to version `7.x.x` in your `package.json` using `resolutions` (for Yarn) or `overrides` (for npm) to force an older, compatible version of `glob`.","message":"When using `express-openapi` with nested routes or complex file structures, an older version of the `glob` dependency (prior to v8) can cause `SyntaxError: Invalid regular expression` errors during initialization due to changes in how `glob` handles paths.","severity":"gotcha","affected_versions":"<12.x"},{"fix":"Always use an OpenAPI diff tool (e.g., `openapi-changes`, `spectral diff`) to compare your old and new API definitions before deploying. Communicate breaking changes to API consumers and provide migration guides. Ensure your client-side code is compatible with the new specification.","message":"Upgrading your OpenAPI specification from 2.0 to 3.0, or from 3.0 to 3.1 (when supported by `express-openapi`), can introduce breaking changes to your API contract. `express-openapi` itself supports both 2.0 and 3.0, but changes in your API definition (e.g., parameter locations, schema structure, nullable types in 3.1) can break existing clients.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Refer to the `express-openapi` documentation for the specific version you are using to confirm the current behavior and supported vendor extensions for middleware configuration. Test your middleware chain thoroughly after any updates.","message":"Configuration of middleware (e.g., coercion, validation, defaults) can be done via vendor extensions like `x-express-openapi-disable-middleware`, `x-express-openapi-additional-middleware`. While powerful, these extensions are specific to `express-openapi` and their behavior or availability might evolve across major versions, potentially requiring adjustments to your `apiDoc` configuration.","severity":"gotcha","affected_versions":">=0.7.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Add `\"resolutions\": { \"glob\": \"7.x.x\" }` (for Yarn) or `\"overrides\": { \"glob\": \"7.x.x\" }` (for npm) to your `package.json` to force an older, compatible version of `glob`.","cause":"An incompatibility between a newer version of the `glob` dependency and `express-openapi`'s path parsing logic, particularly with nested route directory names.","error":"SyntaxError: Invalid regular expression: /^\\/v2\\/users\\((?: ..."},{"fix":"Review the exact validation error messages (often available in the response body or server logs). Adjust the client request to match the API's OpenAPI definition, or update the `apiDoc` if the specification is incorrect.","cause":"The incoming request body, parameters, or headers do not conform to the rules defined in your OpenAPI specification (`apiDoc`) for the requested endpoint.","error":"HTTP 400 Bad Request or validation errors on API calls."},{"fix":"Ensure `initialize({ ..., docsPath: '/your-docs-path' })` matches `app.use('/your-docs-path', swaggerUi.serve, swaggerUi.setup(apiDoc));`. Verify `apiDoc` is a valid OpenAPI document with at least `info` and `openapi` fields.","cause":"Swagger UI is not correctly initialized, the `docsPath` in `express-openapi.initialize` does not match the path used to serve Swagger UI, or the `apiDoc` is invalid or missing required `info` fields.","error":"Cannot GET /api-docs (or other configured Swagger UI path)"}],"ecosystem":"npm"}