Combines multiple Swagger schemas into one dereferenced schema.
$ npm install --save swagger-combine
const swaggerCombine = require('swagger-combine');
swaggerCombine('docs/swagger.json')
.then(combinedSchema => console.log(JSON.stringify(combinedSchema)))
.catch(err => console.error(err));
Swagger Combine returns a promise by default. Alternatively a callback can be passed as second argument:
swaggerCombine('docs/swagger.json', (err, res) => {
if (err) console.error(err);
console.log(JSON.stringify(res));
});
const swaggerCombine = require('swagger-combine');
const app = require('express')();
app.get('/swagger.json', swaggerCombine.middleware('docs/swagger.json'));
app.get('/swagger.yaml', swaggerCombine.middleware('docs/swagger.json', { format: 'yaml' }));
app.listen(3333);
The middleware runs the combine function on every request. Since Swagger documentations tend not to change that frequently, the use of a caching mechanism like apicache is encouraged in conjungtion with this middleware.
- Swagger Combine requires one configuration schema which resembles a standard Swagger schema except for an additional
apis
field. - Since this module uses Swagger Parser and JSON Schema $Ref Parser internally the schema can be passed to Swagger Combine as a file path, a URL or a JS object.
- All
$ref
fields in the configuration schema are getting dereferenced. - The default path for the configuration file is
docs/swagger.json
. - The configuration file can be
JSON
orYAML
.
swagger.json
{
"swagger": "2.0",
"info": {
"title": "Basic Swagger Combine Example",
"version": "1.0.0"
},
"apis": [
{
"url": "http://petstore.swagger.io/v2/swagger.json"
},
{
"url": "https://api.apis.guru/v2/specs/medium.com/1.0.0/swagger.yaml"
},
{
"url": "https://api.apis.guru/v2/specs/deutschebahn.com/betriebsstellen/v1/swagger.json",
"paths": {
"base": "/bahn"
}
}
]
}
swagger.yaml
swagger: '2.0'
info:
title: Basic Swagger Combine Example
version: 1.0.0
apis:
- url: 'http://petstore.swagger.io/v2/swagger.json'
- url: 'https://api.apis.guru/v2/specs/medium.com/1.0.0/swagger.yaml'
- url: 'https://api.apis.guru/v2/specs/deutschebahn.com/betriebsstellen/v1/swagger.json'
paths:
base: '/bahn'
All example configurations are located in the examples
folder.
Paths can be filtered by using an array of paths to exclude
or include
.
{
"swagger": "2.0",
"info": {
"title": "Swagger Combine Filter Example",
"version": "1.0.0"
},
"apis": [
{
"url": "http://petstore.swagger.io/v2/swagger.json",
"paths": {
"exclude": [
"/pet/{petId}",
"/pet.put"
]
}
},
{
"url": "https://api.apis.guru/v2/specs/medium.com/1.0.0/swagger.yaml",
"paths": {
"include": [
"/users/{userId}/publications",
"/me.get"
]
}
}
]
}
Parameters can be filtered by specifying the path and the parameter name as to exclude
or include
as key/value pairs in paths.parameters
.
{
"swagger": "2.0",
"info": {
"title": "Swagger Combine Filter Example",
"version": "1.0.0"
},
"apis": [
{
"url": "http://petstore.swagger.io/v2/swagger.json",
"paths": {
"parameters": {
"exclude": {
"/pet/findByStatus": "status"
}
}
}
},
{
"url": "https://api.apis.guru/v2/specs/medium.com/1.0.0/swagger.yaml",
"paths": {
"include": [
"/users/{userId}/publications",
"/publications/{publicationId}/posts",
"/me.get"
],
"parameters": {
"include": {
"/publications/{publicationId}/posts.post": "publicationId"
}
}
}
}
]
}
Paths can be renamed by specifying the path to rename and the new path name as key/value pairs in paths.rename
.
{
"swagger": "2.0",
"info": {
"title": "Swagger Combine Rename Example",
"version": "1.0.0"
},
"apis": [
{
"url": "http://petstore.swagger.io/v2/swagger.json",
"paths": {
"rename": {
"/pet/{petId}": "/pet/alive/{petId}"
}
}
},
{
"url": "https://api.apis.guru/v2/specs/medium.com/1.0.0/swagger.yaml"
}
]
}
Tags can be renamed in the same manner as paths, using the tags.rename
field.
{
"swagger": "2.0",
"info": {
"title": "Swagger Combine Rename Example",
"version": "1.0.0"
},
"apis": [
{
"url": "http://petstore.swagger.io/v2/swagger.json"
},
{
"url": "https://api.apis.guru/v2/specs/medium.com/1.0.0/swagger.yaml",
"tags": {
"rename": {
"Users": "People"
}
}
}
]
}
Tags can be added to all operations in a schema, using the tags.add
field.
{
"swagger": "2.0",
"info": {
"title": "Swagger Combine Rename Example",
"version": "1.0.0"
},
"apis": [
{
"url": "http://petstore.swagger.io/v2/swagger.json",
"tags": {
"add": [
"pet"
]
}
},
{
"url": "https://api.apis.guru/v2/specs/medium.com/1.0.0/swagger.yaml",
"tags": {
"add": [
"medium"
]
}
}
]
}
Security definitions can be renamed like paths and tags in the securityDefinitions.rename
field. All usages of the security definition in the paths are renamed as well.
{
"swagger": "2.0",
"info": {
"title": "Swagger Combine Rename Example",
"version": "1.0.0"
},
"apis": [
{
"url": "http://petstore.swagger.io/v2/swagger.json",
"securityDefinitions": {
"rename": {
"api_key": "KEY"
}
}
},
{
"url": "https://api.apis.guru/v2/specs/medium.com/1.0.0/swagger.yaml"
}
]
}
Security can be specified per path using the paths.security
field.
{
"swagger": "2.0",
"info": {
"title": "Swagger Combine Security Example",
"version": "1.0.0"
},
"apis": [
{
"url": "http://petstore.swagger.io/v2/swagger.json",
"paths": {
"security": {
"/store/order": {
"petstore_auth": [
"write:pets",
"read:pets"
]
},
"/store/order/{orderId}.delete": {
"petstore_auth": [
"write:pets",
"read:pets"
]
}
}
}
},
{
"url": "https://api.apis.guru/v2/specs/medium.com/1.0.0/swagger.yaml"
}
]
}
Returns promise
with dereferenced and combined schema.
string|object
URL/path to config schema file or config schema object.
Default:
docs/swagger.json
object
(optional)
See JSON Schema $Ref Parser Options for a complete list of options.
function(err, combinedSchema)
(optional)
Callback with error and the dereferenced and combined schema.
Returns function(req, res, next)
for usage as middleware.
string|object
URL/path to config schema file or config schema object.
Default:
docs/swagger.json
object
(optional)
Additional options
-
format -
string
Content type of the response.
yaml
orjson
(default). -
continueOnError -
boolean
Continue if Swagger configs cannot be resolved or are invalid (default:
false
). No warning or error message is returned if this option is enabled.
See JSON Schema $Ref Parser Options for a list of options for the parser.