Registry /
http-networking / swagger-node-runner-fixed
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
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
swaggerRunner
✓ const swaggerRunner = require('swagger-node-runner-fixed');
✗ import swaggerRunner from 'swagger-node-runner-fixed';
This package is primarily designed for CommonJS environments.
run
✓ swaggerRunner.run(app, config, callback);
The `run` method is the main entry point to initialize the Swagger middleware with your application instance and configuration.
Swagger definitions (YAML/JSON)
✓ const swaggerDoc = yaml.load(fs.readFileSync(swaggerPath, 'utf8'));
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.
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.
const express = require('express');
const app = express();
const swaggerRunner = require('swagger-node-runner-fixed');
const path = require('path');
const fs = require('fs');
const yaml = require('js-yaml');
const port = process.env.PORT || 3000;
const swaggerSpecPath = path.resolve(__dirname, './api/swagger/swagger.yaml');
const controllersPath = path.resolve(__dirname, './api/controllers');
// Ensure required directories exist for demonstration
if (!fs.existsSync(path.dirname(swaggerSpecPath))) fs.mkdirSync(path.dirname(swaggerSpecPath), { recursive: true });
if (!fs.existsSync(controllersPath)) fs.mkdirSync(controllersPath, { recursive: true });
// Minimal swagger.yaml for quickstart (create this file manually at ./api/swagger/swagger.yaml)
fs.writeFileSync(swaggerSpecPath, `swagger: "2.0"
info:
title: "My API"
version: "1.0.0"
basePath: /
paths:
/hello:
get:
operationId: helloWorld
responses:
200:
description: "OK"
schema:
type: string
`);
// Minimal controller (create this file manually at ./api/controllers/hello_world.js)
fs.writeFileSync(path.join(controllersPath, 'hello_world.js'), `module.exports = {
helloWorld: function(req, res) {
res.send('Hello from Swagger!');
}
};
`);
// Load the Swagger definition
const swaggerDoc = yaml.load(fs.readFileSync(swaggerSpecPath, 'utf8'));
const config = {
appRoot: __dirname, // Required for swagger-node-runner to find controllers
swagger: swaggerDoc,
controllers: controllersPath // Path to your API controllers
};
swaggerRunner.run(app, config, function(err) {
if (err) {
console.error('Failed to initialize swagger-node-runner:', err.message);
process.exit(1);
}
// swagger-node-runner-fixed will automatically attach middleware and routes
app.listen(port, () => {
console.log(`Server running on http://localhost:${port}`);
console.log(`Try: curl http://localhost:${port}/hello`);
console.log(`Swagger UI is typically available at http://localhost:${port}/docs (if configured via fittings)`);
});
});
Debug
Known issues
breakingThis 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.fixEnsure 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"`.
affects: <1.0.0 (original fork target)
breakingThe 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.fixReview 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.
affects: >=0.6.0
breakingThe `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.fixReplace `cors` with `swagger-cors` in your application's middleware pipe configuration (e.g., in `config/default.yaml` or similar fitting definitions).
affects: >=0.7.1
gotchaThe `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.fixTo include error stacks, set `includeErrStack: true` under your `openapi-error` configuration in your application's config files (e.g., `config/default.yaml`).
affects: >=0.7.1
gotchaResponse 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.fixTo catch validation errors, listen for the `'responseValidationError'` event on the runner instance. Example: `runner.on('responseValidationError', (err) => { console.error('Response validation error:', err); });`. affects: >=0.6.4
gotchaThe `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.fixReview 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.
affects: >=0.6.11
gotchaSecurity 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.fixConsider migrating your security handler setup to use the `securityHandlersModule` setting within the `swagger_security` fitting configuration. This centralizes security logic lookup.
affects: >=0.6.10
Errors
Common errors & fixes
Error: Failed to initialize swagger-node-runner: Cannot read property 'type' of undefined (or similar 'Cannot read property' errors during startup)
Often caused by an invalid or malformed Swagger/OpenAPI definition file (YAML/JSON). The parser cannot correctly interpret a part of the schema.
fixValidate your `swagger.yaml` or `swagger.json` file rigorously using an online OpenAPI/Swagger validator. Pay close attention to syntax, indentation, and required fields.
Error: 'appRoot' is required
`swagger-node-runner-fixed` requires an `appRoot` property in its configuration options to correctly locate controllers and other application resources.
fixEnsure your configuration object passed to `swaggerRunner.run()` includes `appRoot: __dirname` or the absolute path to your application's root directory.
TypeError: Cannot find module 'swagger-tools'
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`.
fixUpdate your code and configurations to be compatible with `Sway`. Remove any direct dependencies or references to `swagger-tools` from your project.
Error: ENOENT: no such file or directory, stat './api/swagger/swagger.yaml'
The configured path to your Swagger/OpenAPI definition file is incorrect, or the file does not exist at the specified location.
fixDouble-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.
Error: Operation 'myOperationId' not found for path '/my-path' (or similar routing errors)
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.
fixEnsure 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.
Audit
Dependencies
swayrequiredCore library for Swagger/OpenAPI definition parsing, validation, and processing.
js-yamlrequiredUsed for loading YAML-based Swagger/OpenAPI definitions.
expressoptionalCommonly used web framework with which swagger-node-runner-fixed integrates as middleware. Not a direct dependency but a typical peer environment.