Registry / devops / swagger-combine

swagger-combine

JSON →
library1.4.0jsnpmunverified

Combines multiple Swagger/OpenAPI 2.0 schemas into a single dereferenced schema. Version 1.4.0 is the latest stable release, with no recent updates; the package is in maintenance mode. Key differentiators: supports merging APIs from local files, URLs, and objects; provides both Promise and callback APIs; includes Express middleware for serving the combined schema; and offers a CLI for quick merging. Unlike alternatives like swagger-merger or api-spec-converter, it focuses purely on combining Swagger 2.0 specs without transformation to OpenAPI 3.

devops
npm install swagger-combine
github ↗package ↗homepage ↗
INSTALL
IMPORT
SIG · SWAGGER-COMBINE
S
swagger-combine
devopsjavascriptv1.4.0
harness data pending
Install & Compatibility
Where this runs

No compatibility data collected yet for this library.

Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

default
✓ const swaggerCombine = require('swagger-combine')
✗ import swaggerCombine from 'swagger-combine'
This package does not ship ESM; use CommonJS require().
swaggerCombine.middleware
✓ const { middleware } = require('swagger-combine')
✗ import { middleware } from 'swagger-combine'
Also accessed via swaggerCombine.middleware, but destructuring is fine.
swaggerCombine.middlewareAsync
✓ const { middlewareAsync } = require('swagger-combine')
async variant that returns a middleware function; only available via require.

Demonstrates basic usage: loading a config file, combining APIs, and handling the result or error.

const swaggerCombine = require('swagger-combine'); // Combine multiple Swagger schemas defined in a config file swaggerCombine('docs/swagger.json') .then(combinedSchema => { console.log(JSON.stringify(combinedSchema, null, 2)); }) .catch(err => { console.error('Error combining schemas:', err.message); }); // Example config file (swagger.json): // { // "swagger": "2.0", // "info": { "title": "Combined API", "version": "1.0.0" }, // "apis": [ // { "url": "http://petstore.swagger.io/v2/swagger.json" }, // { "url": "https://api.example.com/swagger.yaml", "paths": { "base": "/external" } } // ] // }
Debug
Known issues
breakingThe combine function now returns a Promise and no longer supports synchronous operation.
fix
Always use .then()/catch() or async/await, or pass a callback as second argument.
affects: >=1.0.0
gotchaAll $ref references in the configuration schema are dereferenced; this may break circular references or very large schemas.
fix
Avoid circular $ref chains; consider using JSON Schema $Ref Parser options if needed.
affects: >=1.0.0
gotchaThe 'apis' array paths.base option prepends a base path to all paths from that API; ensure no double slashes.
fix
Use a leading slash only (e.g., "/api") and avoid trailing slash in base.
affects: >=1.0.0
deprecatedThis package only supports Swagger 2.0, not OpenAPI 3.0.
fix
For OpenAPI 3.0, consider using api-spec-converter or swagger-merger.
affects: >=1.0.0
Errors
Common errors & fixes
Error: ENOENT: no such file or directory, open 'docs/swagger.json'
The default config file path 'docs/swagger.json' does not exist.
fix
Ensure the config file exists at the path passed to swaggerCombine(), or create one.
TypeError: swaggerCombine is not a function
Using ES6 import syntax which is not supported.
fix
Use const swaggerCombine = require('swagger-combine');
UnhandledPromiseRejectionWarning: TypeError: Cannot read property 'paths' of undefined
The combined schema contains an API definition without a 'paths' property, or the config is malformed.
fix
Validate that all API definitions in the 'apis' array have valid Swagger/OpenAPI 2.0 structure.
Upgrade
Version history
1.4.0latest on npm
Audit
Dependencies
json-refsrequiredresolves JSON references within the combined schema
swagger-parserrequiredvalidates and parses Swagger definitions
yamljsrequiredsupports YAML input and output
Agent activity
5 hits · last 30 days
node
4
Amazon
1
Resources
githubhttps://github.com/maxdome/swagger-combine ↗
packageswagger-combine ↗
homepagehttps://github.com/maxdome/swagger-combine#readme ↗
swagger-combine — npm install swagger-combine · libregistry