{"id":17967,"library":"swagger-express-fixed","title":"Swagger Express Fixed Middleware","description":"swagger-express-fixed is a specialized fork of the legacy apigee-127/swagger-express library, designed to provide critical compatibility fixes for Node.js environments beyond version 10. The package, currently at version 1.0.2, aims to enable older Express applications that rely on the original `swagger-express` to run on modern Node.js runtimes without necessitating a complete rewrite to contemporary OpenAPI tooling like `swagger-ui-express` and `swagger-jsdoc`. It achieves this by integrating an updated `swagger-node-runner` (or its fixed variant), which now utilizes the `Sway` engine for robust API validation. This fork prioritizes stability and bug fixes over new feature development, making its release cadence infrequent and focused on critical maintenance for existing projects.","status":"maintenance","version":"1.0.2","language":"javascript","source_language":"en","source_url":"https://github.com/apigee-127/swagger-express","tags":["javascript","swagger","api","apis","connect"],"install":[{"cmd":"npm install swagger-express-fixed","lang":"bash","label":"npm"},{"cmd":"yarn add swagger-express-fixed","lang":"bash","label":"yarn"},{"cmd":"pnpm add swagger-express-fixed","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core component responsible for loading Swagger/OpenAPI definitions and managing the runtime aspects of the API.","package":"swagger-node-runner","optional":false},{"reason":"Required peer dependency for any Express application middleware.","package":"express","optional":false}],"imports":[{"note":"The package primarily uses CommonJS `require` syntax. Direct ESM `import` is not officially supported and may require transpilation or specific module resolution configurations.","wrong":"import { create } from 'swagger-express-fixed';","symbol":"create","correct":"const swagger = require('swagger-express-fixed');\n// Then use: swagger.create(options, callback)"},{"note":"Similar to `create`, `init` is typically accessed via the CommonJS default export. Ensure `app` is your Express application instance.","wrong":"import { init } from 'swagger-express-fixed';","symbol":"init","correct":"const swagger = require('swagger-express-fixed');\napp.use(swagger.init(app, options));"}],"quickstart":{"code":"const express = require('express');\nconst path = require('path');\nconst swagger = require('swagger-express-fixed');\n\nconst app = express();\nconst port = 3000;\n\nconst config = {\n  appRoot: __dirname, // required for swagger-node-runner\n  swaggerFile: path.resolve(__dirname, './api/swagger.yaml') // Path to your API definition\n};\n\n/* Example swagger.yaml content (place in ./api/swagger.yaml)\n---\nswagger: '2.0'\ninfo:\n  title: My Express API\n  version: '1.0.0'\npaths:\n  /hello:\n    get:\n      summary: Returns a greeting\n      responses:\n        200:\n          description: A simple greeting\n          schema:\n            type: string\n*/\n\nswagger.create(config, function(err, swaggerMiddleware) {\n  if (err) { throw err; }\n\n  // Add swagger-express-fixed middleware to your Express app\n  app.use(swaggerMiddleware.swaggerSecurity({})\n  app.use(swaggerMiddleware.swaggerMetadata());\n  app.use(swaggerMiddleware.swaggerValidator());\n  app.use(swaggerMiddleware.swaggerRouter({ useStubs: true }));\n  app.use(swaggerMiddleware.swaggerUi());\n\n  // Custom error handler (optional)\n  app.use(function(err, req, res, next) {\n    if (err.statusCode) {\n      res.status(err.statusCode).json(err.message);\n    } else {\n      res.status(500).json('Internal Server Error');\n    }\n  });\n\n  app.listen(port, () => {\n    console.log(`Server running at http://localhost:${port}`);\n    console.log(`Swagger UI available at http://localhost:${port}/docs`);\n  });\n});\n","lang":"javascript","description":"Demonstrates how to initialize `swagger-express-fixed` with a basic Express application, loading a Swagger/OpenAPI definition file and setting up the API routes and UI."},"warnings":[{"fix":"Migrate to `swagger-express-fixed` for Node.js > 10 compatibility, or update to more modern OpenAPI documentation tools like `swagger-ui-express` and `swagger-jsdoc`.","message":"The original `apigee-127/swagger-express` is known to be incompatible with Node.js versions greater than 10. This `_fixed` fork specifically addresses these runtime issues. Attempting to use the unpatched version on newer Node.js runtimes will result in crashes or unexpected behavior.","severity":"breaking","affected_versions":"<1.0.0 (original package)"},{"fix":"Thoroughly test API endpoints after upgrading, paying close attention to request validation, response generation, and error handling for any regressions or stricter enforcement of the OpenAPI specification. Refer to `swagger-node-runner` release notes.","message":"The underlying `swagger-node-runner` dependency, used by this package, transitioned to a 'Sway-based release' in version `0.6.0`. This change introduces a new validation engine, which might alter API behavior or strictness compared to older versions, potentially breaking existing API contracts if not carefully reviewed.","severity":"breaking","affected_versions":">=0.6.0 (of swagger-node-runner, implicitly affecting this package)"},{"fix":"Ensure your Express application is configured with appropriate CORS middleware (e.g., `cors` package) to allow requests from the Swagger UI origin. Verify `basePath` in your Swagger definition matches your application's deployment path.","message":"Cross-Origin Resource Sharing (CORS) issues are common when serving Swagger UI, especially if the API and the UI are on different origins, or if the API definitions themselves have CORS-related misconfigurations. This can lead to the Swagger UI failing to load API definitions or make requests.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure your Swagger/OpenAPI definition adheres to the 2.0 specification for full compatibility. If migrating to OpenAPI 3.x, consider using dedicated 3.x compatible tools like `swagger-ui-express` with `swagger-jsdoc` or `express-openapi`.","message":"This package is primarily built for Swagger/OpenAPI 2.0 specifications. While OpenAPI 3.x is the current standard, using a 3.x definition directly with this tool might lead to parsing errors or unexpected behavior as it may not fully support the newer specification structure (e.g., `components` object, `requestBody`).","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"fix":"Ensure you are using `swagger-express-fixed` and that its internal dependencies are correctly resolved. Verify `package-lock.json` and `node_modules` structure. If this error persists, consider a clean `npm install`.","cause":"The original `swagger-express` package or an unpatched `swagger-node-runner` is being used with a Node.js version greater than 10, leading to module loading or dependency resolution failures.","error":"TypeError: Cannot read property 'swaggerUi' of undefined"},{"fix":"Carefully review the specified line and column in your `swagger.yaml` file for syntax errors, improper indentation, or schema violations. Use an OpenAPI/Swagger editor or linter (e.g., `swagger-cli validate`) to validate your YAML file.","cause":"Syntax error, incorrect indentation, or invalid schema in the provided Swagger/OpenAPI YAML definition file. YAML is sensitive to whitespace and structure.","error":"YAMLSemanticError: (in ..., at line x, column y)"},{"fix":"Verify the `apis` array in your `config` object (or `swagger.yaml`) contains the correct relative or absolute paths to your API definition files. Ensure file names and extensions match and are accessible from the `appRoot`.","cause":"The `apis` configuration in `swagger-express-fixed` (or its underlying `swagger-node-runner`) does not correctly point to your API definition files (e.g., `swagger.yaml` or `controller` files).","error":"Error: The 'apis' array is empty. No files were found matching the provided paths."},{"fix":"Implement a CORS middleware in your Express application that explicitly allows requests from the origin where your Swagger UI is hosted. This might involve setting `Access-Control-Allow-Origin` headers. Ensure the `swaggerURL` and `basePath` are correctly configured in `swagger.init` options.","cause":"The Swagger UI, often served on a different path or port than the API, is blocked by browser security policies from fetching the API definition JSON due to a missing or misconfigured CORS header.","error":"Failed to load API definition. Possible cross-origin (CORS) issue?"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}