{"id":17972,"library":"swagger-node-runner","title":"Swagger Node.js API Middleware Runner","description":"swagger-node-runner is a middleware engine designed to integrate Swagger (now OpenAPI) definitions with various Node.js web frameworks, including Connect, Express, Restify, Hapi, and Sails. It handles the loading and processing of API definitions, routing, and applying middleware based on the specification. The package is currently at version 0.7.3, with its last known release in October 2016. Its primary differentiation from earlier solutions was the complete replacement of `swagger-tools` with the `Sway` library starting from version 0.6.0, which was further updated to `Sway 1.0` in version 0.7.0. Due to its age and lack of recent updates, the project appears to be abandoned, meaning it does not receive new features, bug fixes, or security patches. Developers should exercise caution regarding its compatibility with modern Node.js versions and potential security vulnerabilities in its outdated dependencies.","status":"abandoned","version":"0.7.3","language":"javascript","source_language":"en","source_url":"https://github.com/theganyo/swagger-node-runner","tags":["javascript","swagger","api","apis","swagger-connect","swagger-express","swagger-restify","swagger-hapi","swagger-sails"],"install":[{"cmd":"npm install swagger-node-runner","lang":"bash","label":"npm"},{"cmd":"yarn add swagger-node-runner","lang":"bash","label":"yarn"},{"cmd":"pnpm add swagger-node-runner","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core library for Swagger/OpenAPI parsing and validation since v0.6.0, replacing swagger-tools.","package":"sway","optional":false},{"reason":"Peer dependencies for integration with specific Node.js web frameworks. Choose one based on your application.","package":"express|connect|restify|hapi|sails","optional":true}],"imports":[{"note":"The package is CommonJS-only and exports an object with a 'create' method. ESM imports are not supported in this abandoned project.","wrong":"import { create } from 'swagger-node-runner';","symbol":"create","correct":"const runner = require('swagger-node-runner').create(config);"},{"note":"Prior to v0.6.0, `swagger-node-runner` indirectly relied on `swagger-tools` for Swagger UI. Post v0.6.0, direct UI integration needs a separate package like `swagger-ui-express`, as `swagger-tools` was replaced by `Sway`.","wrong":"const swaggerUi = require('swagger-node-runner').swaggerUi;","symbol":"SwaggerUI","correct":"const swaggerTools = require('swagger-tools'); // Only if using v0.5.x or older"},{"note":"Configuration for `swagger-node-runner` is typically a plain JavaScript object passed to the `create` method, not a class instance.","wrong":"const config = new SwaggerNodeRunner.Config();","symbol":"ConfigObject","correct":"const config = { appRoot: __dirname, swaggerFile: '/path/to/swagger.yaml' };"}],"quickstart":{"code":"const express = require('express');\nconst SwaggerNodeRunner = require('swagger-node-runner');\nconst path = require('path');\n\nconst app = express();\nconst port = process.env.PORT || 3000;\n\n// Configuration for swagger-node-runner\nconst config = {\n  appRoot: __dirname, // Tells swagger-node-runner where to find controllers and fittings\n  swaggerFile: path.resolve(__dirname, 'api', 'swagger', 'swagger.yaml'),\n  // Example of a security handler configuration (uncomment and customize if needed)\n  // swaggerSecurityHandlers: {\n  //   ApiKeyAuth: function (req, authOrSecDef, scopes, callback) {\n  //     // Simulate API key validation using an environment variable\n  //     if (req.headers['x-api-key'] === (process.env.API_KEY || 'your-secret-key')) {\n  //       callback();\n  //     } else {\n  //       callback(new Error('Access denied: Invalid API Key'));\n  //     }\n  //   }\n  // }\n};\n\nSwaggerNodeRunner.create(config, function (err, runner) {\n  if (err) { throw err; }\n\n  // Install the Swagger Express middleware provided by the runner\n  runner.expressMiddleware().register(app);\n\n  // For Swagger UI, you would typically use a separate package (e.g., swagger-ui-express)\n  // Example: app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(runner.swagger.parsed));\n\n  app.listen(port, function () {\n    console.log(`Your API is running at http://localhost:${port}`);\n    console.log(`Swagger UI (if configured separately) would be available at /api-docs`);\n  });\n});\n\n// --- Minimal example files to make the above code runnable ---\n// Save this as api/swagger/swagger.yaml:\n/*\nswagger: '2.0'\ninfo:\n  title: Example API\n  version: '1.0.0'\nbasePath: /v1\npaths:\n  /hello:\n    x-swagger-router-controller: hello_world\n    get:\n      description: Returns 'Hello, World!'\n      operationId: hello\n      responses:\n        '200':\n          description: Success\n          schema:\n            type: string\n*/\n\n// Save this as api/controllers/hello_world.js:\n/*\nmodule.exports = {\n  hello: function (req, res) {\n    res.json('Hello, World!');\n  }\n};\n*/","lang":"javascript","description":"This quickstart demonstrates how to set up a basic Express application with `swagger-node-runner`. It loads an OpenAPI (Swagger 2.0) definition, registers the middleware for API routing and handling, and includes commented examples for a basic Swagger YAML file, a controller, and API key authentication."},"warnings":[{"fix":"Review the v0.6.0 release notes on GitHub for detailed upgrade instructions and adapt your code to `Sway`'s API or `swagger-node-runner`'s new middleware structure.","message":"Version 0.6.0 completely replaced `swagger-tools` with the `Sway` library for Swagger/OpenAPI parsing and validation. Projects upgrading from versions prior to 0.6.0 must follow specific upgrade instructions, as direct API calls to `swagger-tools` will no longer work.","severity":"breaking","affected_versions":">=0.6.0"},{"fix":"Test your application thoroughly after upgrading to v0.7.0 to identify any regressions or behavioral changes due to `Sway 1.0`. Consult `Sway`'s release notes for specific breaking changes.","message":"Version 0.7.0 upgraded the underlying `Sway` library to `Sway 1.0`. While release notes primarily mentioned enhancements and fixes, a major version bump of a core dependency often introduces breaking changes or significant behavioral shifts that may impact existing implementations.","severity":"breaking","affected_versions":">=0.7.0"},{"fix":"Replace `cors` with `swagger-cors` in your middleware pipe (e.g., in `config/default.yaml`) and ensure your `fittingsDirs` configuration includes your `node_modules` path if `swagger-cors` is a direct dependency.","message":"The `cors` fitting was deprecated in favor of `swagger-cors` in version 0.7.1. If you are using the `cors` fitting, you should consider migrating to `swagger-cors` for potential enhancements and better integration.","severity":"gotcha","affected_versions":">=0.7.1"},{"fix":"Consider migrating to a modern OpenAPI/Swagger framework or middleware, such as `express-openapi`, `fastify-swagger`, or manually integrating `swagger-ui-express` with a routing library, to ensure ongoing support and security.","message":"The package `swagger-node-runner` is effectively abandoned, with its last release in October 2016. This means it no longer receives bug fixes, new features, or security updates. Using it in production carries risks of unpatched vulnerabilities and compatibility issues with newer Node.js versions or dependencies.","severity":"gotcha","affected_versions":"all"},{"fix":"Be aware that `x-private: true` tags will hide parts of your API from the served Swagger definition. If you need to override this, check the `privateTags` configuration option for `swagger_raw`.","message":"The `swagger_raw` fitting gained support for `x-private: true` tags in v0.6.11. Objects (like paths or operations) marked with this tag in your Swagger definition will be excluded from the served Swagger API, which might lead to unexpected behavior if not understood.","severity":"gotcha","affected_versions":">=0.6.11"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"fix":"Ensure the package is installed using `npm install swagger-node-runner` and that your `require('swagger-node-runner')` statement points to the correct module.","cause":"The 'swagger-node-runner' package is not installed or the path in your `require` statement is incorrect.","error":"Error: Cannot find module 'swagger-node-runner'"},{"fix":"Carefully review the validation error messages provided by the runner. Use a Swagger/OpenAPI editor (e.g., Swagger Editor online) to validate your API definition file and correct any syntax or schema issues.","cause":"Your `swagger.yaml` or `swagger.json` file contains errors that violate the OpenAPI (Swagger 2.0) specification.","error":"Swagger validation failed: { /* details about validation errors */ }"},{"fix":"Update your application code to use `swagger-node-runner`'s new API methods or `Sway`'s API for parsing and validation, as direct calls to `swagger-tools` functionality are no longer supported by `swagger-node-runner` itself.","cause":"This error often occurs when code written for older versions (pre-v0.6.0) that directly interacted with `swagger-tools` is run on v0.6.0 or newer, where `swagger-tools` has been replaced by `Sway`.","error":"TypeError: Cannot read property 'parse' of undefined"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}