{"id":17970,"library":"swagger-node-runner-fixed","title":"Swagger Node.js API Runner (Fixed)","description":"`swagger-node-runner-fixed` is a maintained fork of the original `apigee-127/swagger-node-runner`, primarily addressing compatibility issues with Node.js versions greater than 10. It serves as a comprehensive loader and middleware utility for building API projects based on Swagger/OpenAPI specifications, seamlessly integrating with popular Node.js web frameworks like Express, Restify, and Hapi. The package's current stable version is 1.0.1. Its core functionality involves interpreting a Swagger definition, applying various 'fittings' (middleware), and routing incoming requests to corresponding controllers based on the API specification. A significant architectural shift occurred in earlier versions (around v0.6.0 and v0.7.0), transitioning the underlying Swagger processing engine from `swagger-tools` to the more robust `Sway` library, which brought improved validation and schema capabilities. The project's release cadence is now infrequent, focusing on critical fixes and maintaining Node.js compatibility rather than extensive feature development.","status":"maintenance","version":"1.0.1","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-fixed","lang":"bash","label":"npm"},{"cmd":"yarn add swagger-node-runner-fixed","lang":"bash","label":"yarn"},{"cmd":"pnpm add swagger-node-runner-fixed","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core library for Swagger/OpenAPI definition parsing, validation, and processing.","package":"sway","optional":false},{"reason":"Used for loading YAML-based Swagger/OpenAPI definitions.","package":"js-yaml","optional":false},{"reason":"Commonly used web framework with which swagger-node-runner-fixed integrates as middleware. Not a direct dependency but a typical peer environment.","package":"express","optional":true}],"imports":[{"note":"This package is primarily designed for CommonJS environments.","wrong":"import swaggerRunner from 'swagger-node-runner-fixed';","symbol":"swaggerRunner","correct":"const swaggerRunner = require('swagger-node-runner-fixed');"},{"note":"The `run` method is the main entry point to initialize the Swagger middleware with your application instance and configuration.","symbol":"run","correct":"swaggerRunner.run(app, config, callback);"},{"note":"While not a direct import from the package, loading your Swagger definition is a critical preliminary step. `js-yaml` is a common dependency for YAML files.","symbol":"Swagger definitions (YAML/JSON)","correct":"const swaggerDoc = yaml.load(fs.readFileSync(swaggerPath, 'utf8'));"}],"quickstart":{"code":"const express = require('express');\nconst app = express();\nconst swaggerRunner = require('swagger-node-runner-fixed');\nconst path = require('path');\nconst fs = require('fs');\nconst yaml = require('js-yaml');\n\nconst port = process.env.PORT || 3000;\nconst swaggerSpecPath = path.resolve(__dirname, './api/swagger/swagger.yaml');\nconst controllersPath = path.resolve(__dirname, './api/controllers');\n\n// Ensure required directories exist for demonstration\nif (!fs.existsSync(path.dirname(swaggerSpecPath))) fs.mkdirSync(path.dirname(swaggerSpecPath), { recursive: true });\nif (!fs.existsSync(controllersPath)) fs.mkdirSync(controllersPath, { recursive: true });\n\n// Minimal swagger.yaml for quickstart (create this file manually at ./api/swagger/swagger.yaml)\nfs.writeFileSync(swaggerSpecPath, `swagger: \"2.0\"\ninfo:\n  title: \"My API\"\n  version: \"1.0.0\"\nbasePath: /\npaths:\n  /hello:\n    get:\n      operationId: helloWorld\n      responses:\n        200:\n          description: \"OK\"\n          schema:\n            type: string\n`);\n\n// Minimal controller (create this file manually at ./api/controllers/hello_world.js)\nfs.writeFileSync(path.join(controllersPath, 'hello_world.js'), `module.exports = {\n  helloWorld: function(req, res) {\n    res.send('Hello from Swagger!');\n  }\n};\n`);\n\n// Load the Swagger definition\nconst swaggerDoc = yaml.load(fs.readFileSync(swaggerSpecPath, 'utf8'));\n\nconst config = {\n  appRoot: __dirname, // Required for swagger-node-runner to find controllers\n  swagger: swaggerDoc,\n  controllers: controllersPath // Path to your API controllers\n};\n\nswaggerRunner.run(app, config, function(err) {\n  if (err) {\n    console.error('Failed to initialize swagger-node-runner:', err.message);\n    process.exit(1);\n  }\n\n  // swagger-node-runner-fixed will automatically attach middleware and routes\n  app.listen(port, () => {\n    console.log(`Server running on http://localhost:${port}`);\n    console.log(`Try: curl http://localhost:${port}/hello`);\n    console.log(`Swagger UI is typically available at http://localhost:${port}/docs (if configured via fittings)`);\n  });\n});","lang":"javascript","description":"This demonstrates initializing `swagger-node-runner-fixed` with an Express application, loading a local Swagger definition, and starting the server to serve API endpoints defined in the spec and routed to corresponding controllers."},"warnings":[{"fix":"Ensure you are using `swagger-node-runner-fixed` for Node.js environments >= v10. Update your package.json to use `\"swagger-node-runner-fixed\": \"^1.0.0\"`.","message":"This package is a fork specifically created to provide compatibility with Node.js versions greater than 10. Original `swagger-node-runner` versions may not function correctly or at all on modern Node.js runtimes.","severity":"breaking","affected_versions":"<1.0.0 (original fork target)"},{"fix":"Review your code for any direct usage of `swagger-tools` functionality. Adapt configurations and custom logic to align with `Sway`'s API and structure. Refer to `Sway` documentation for updated approaches.","message":"The underlying Swagger processing library `swagger-tools` was completely replaced by `Sway` in v0.6.0. If your application relied on direct interaction with `swagger-tools` APIs or its specific configuration options, these will no longer be available or compatible.","severity":"breaking","affected_versions":">=0.6.0"},{"fix":"Replace `cors` with `swagger-cors` in your application's middleware pipe configuration (e.g., in `config/default.yaml` or similar fitting definitions).","message":"The `swagger-cors` fitting was introduced in v0.7.1 as a replacement for the generic `cors` fitting. Applications using `cors` in their middleware pipe might need to update.","severity":"breaking","affected_versions":">=0.7.1"},{"fix":"To include error stacks, set `includeErrStack: true` under your `openapi-error` configuration in your application's config files (e.g., `config/default.yaml`).","message":"The `json_error_handler` fitting's behavior for including error stack traces in 500 responses is now controlled by the `includeErrStack` flag. By default, error stacks might not be included, potentially hindering debugging in development environments.","severity":"gotcha","affected_versions":">=0.7.1"},{"fix":"To catch validation errors, listen for the `'responseValidationError'` event on the runner instance. Example: `runner.on('responseValidationError', (err) => { console.error('Response validation error:', err); });`.","message":"Response validation changed in v0.6.4. It no longer overwrites API responses but instead emits a `'responseValidationError'` event. Applications expecting automatic response modification will need to implement an event listener.","severity":"gotcha","affected_versions":">=0.6.4"},{"fix":"Review your Swagger definition for `x-private: true` tags. If you wish to override this behavior, configure the `privateTags` setting for `swagger_raw` in your application's configuration.","message":"The `swagger_raw` fitting now supports hiding specific API paths or operations from the served Swagger documentation by tagging them with `x-private: true`. If not configured intentionally, parts of your API might be unexpectedly hidden.","severity":"gotcha","affected_versions":">=0.6.11"},{"fix":"Consider migrating your security handler setup to use the `securityHandlersModule` setting within the `swagger_security` fitting configuration. This centralizes security logic lookup.","message":"Security handlers can now be automatically looked up and installed using the `securityHandlersModule` setting in your configuration. Older programmatic approaches might be less efficient or harder to maintain.","severity":"gotcha","affected_versions":">=0.6.10"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"fix":"Validate your `swagger.yaml` or `swagger.json` file rigorously using an online OpenAPI/Swagger validator. Pay close attention to syntax, indentation, and required fields.","cause":"Often caused by an invalid or malformed Swagger/OpenAPI definition file (YAML/JSON). The parser cannot correctly interpret a part of the schema.","error":"Error: Failed to initialize swagger-node-runner: Cannot read property 'type' of undefined (or similar 'Cannot read property' errors during startup)"},{"fix":"Ensure your configuration object passed to `swaggerRunner.run()` includes `appRoot: __dirname` or the absolute path to your application's root directory.","cause":"`swagger-node-runner-fixed` requires an `appRoot` property in its configuration options to correctly locate controllers and other application resources.","error":"Error: 'appRoot' is required"},{"fix":"Update your code and configurations to be compatible with `Sway`. Remove any direct dependencies or references to `swagger-tools` from your project.","cause":"This error typically occurs if you're trying to use code or configurations designed for older versions of `swagger-node-runner` (pre-v0.6.0) that relied on `swagger-tools`, with the `swagger-node-runner-fixed` package which uses `Sway`.","error":"TypeError: Cannot find module 'swagger-tools'"},{"fix":"Double-check the `swaggerPath` in your application's setup to ensure it correctly points to your `swagger.yaml` or `swagger.json` file. Verify the file's existence and permissions.","cause":"The configured path to your Swagger/OpenAPI definition file is incorrect, or the file does not exist at the specified location.","error":"Error: ENOENT: no such file or directory, stat './api/swagger/swagger.yaml'"},{"fix":"Ensure the `x-swagger-router-controller` and `operationId` in your Swagger definition precisely match the controller file name and exported function names respectively. Verify the `controllers` path in your `swaggerRunner.run()` configuration is correct.","cause":"This indicates a mismatch between the `operationId` specified in your Swagger/OpenAPI definition and the actual function name exported by your controller module, or that the controller file is not found.","error":"Error: Operation 'myOperationId' not found for path '/my-path' (or similar routing errors)"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}