Installations
npm install swagger-combine
Developer Guide
Typescript
No
Module System
CommonJS
Min. Node Version
>=10
Node Version
14.15.4
NPM Version
7.19.0
Score
58.3
Supply Chain
99.2
Quality
74.9
Maintenance
100
Vulnerability
98.6
License
Releases
Unable to fetch releases
Contributors
Unable to fetch Contributors
Languages
JavaScript (100%)
Developer
maxdome
Download Statistics
Total Downloads
3,723,317
Last Day
937
Last Week
26,563
Last Month
144,634
Last Year
1,366,160
GitHub Statistics
133 Stars
237 Commits
37 Forks
10 Watching
7 Branches
9 Contributors
Package Meta Information
Latest Version
1.4.0
Package Id
swagger-combine@1.4.0
Size
18.39 kB
NPM Version
7.19.0
Node Version
14.15.4
Publised On
25 Oct 2021
Total Downloads
Cumulative downloads
Total Downloads
3,723,317
Last day
-69.4%
937
Compared to previous day
Last week
-16%
26,563
Compared to previous week
Last month
-32.3%
144,634
Compared to previous month
Last year
17.1%
1,366,160
Compared to previous year
Daily Downloads
Weekly Downloads
Monthly Downloads
Yearly Downloads
Swagger Combine
Combines multiple Swagger schemas into one dereferenced schema.
Install
1$ npm install --save swagger-combine
Globally for CLI usage
1$ npm install -g swagger-combine
Usage
1const swaggerCombine = require('swagger-combine'); 2 3swaggerCombine('docs/swagger.json') 4 .then(res => console.log(JSON.stringify(res))) 5 .catch(err => console.error(err));
Swagger Combine returns a promise by default. Alternatively a callback can be passed as second argument:
1swaggerCombine('docs/swagger.json', (err, res) => {
2 if (err) console.error(err);
3 else console.log(JSON.stringify(res));
4});
Middleware
1const swaggerCombine = require('swagger-combine'); 2const app = require('express')(); 3 4app.get('/swagger.json', swaggerCombine.middleware('docs/swagger.json')); 5app.get('/swagger.yaml', swaggerCombine.middleware('docs/swagger.json', { format: 'yaml' })); 6app.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.
Async Middleware
1const swaggerCombine = require('swagger-combine'); 2const app = require('express')(); 3 4(async function() { 5 try { 6 app.get('/swagger.json', await swaggerCombine.middlewareAsync('docs/swagger.json')); 7 app.get('/swagger.yaml', await swaggerCombine.middlewareAsync('docs/swagger.json', { format: 'yaml' })); 8 } catch (e) { 9 console.error(e); 10 } 11 12 app.listen(3333); 13})(); 14
CLI
1$ swagger-combine config.json
Help
1$ swagger-combine -h
Save to File
1$ swagger-combine config.json -o combinedSchema.json
YAML Output
The output is in YAML if the output filename ends with .yaml
or .yml
:
1$ swagger-combine config.json -o combinedSchema.yaml
Alternatively the --format
or -f
argument can be used:
1$ swagger-combine config.json -f yaml
Configuration
- 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
.
Basic Configuration
swagger.json
1{ 2 "swagger": "2.0", 3 "info": { 4 "title": "Basic Swagger Combine Example", 5 "version": "1.0.0" 6 }, 7 "apis": [ 8 { 9 "url": "http://petstore.swagger.io/v2/swagger.json" 10 }, 11 { 12 "url": "https://api.apis.guru/v2/specs/medium.com/1.0.0/swagger.yaml" 13 }, 14 { 15 "url": "https://api.apis.guru/v2/specs/deutschebahn.com/betriebsstellen/v1/swagger.json", 16 "paths": { 17 "base": "/bahn" 18 } 19 } 20 ] 21}
swagger.yaml
1swagger: '2.0' 2info: 3 title: Basic Swagger Combine Example 4 version: 1.0.0 5apis: 6 - url: 'http://petstore.swagger.io/v2/swagger.json' 7 - url: 'https://api.apis.guru/v2/specs/medium.com/1.0.0/swagger.yaml' 8 - url: 'https://api.apis.guru/v2/specs/deutschebahn.com/betriebsstellen/v1/swagger.json' 9 paths: 10 base: '/bahn'
All example configurations are located in the examples
folder.
Filtering Paths
Paths can be filtered by using an array of paths and regex strings to exclude
or include
.
1{ 2 "swagger": "2.0", 3 "info": { 4 "title": "Swagger Combine Filter Example", 5 "version": "1.0.0" 6 }, 7 "apis": [ 8 { 9 "url": "http://petstore.swagger.io/v2/swagger.json", 10 "paths": { 11 "exclude": [ 12 "/pet/{petId}", 13 "/pet.put" 14 ] 15 } 16 }, 17 { 18 "url": "https://api.apis.guru/v2/specs/medium.com/1.0.0/swagger.yaml", 19 "paths": { 20 "include": [ 21 "/users/{userId}/publications", 22 "/me.get" 23 ] 24 } 25 } 26 ] 27}
Example of using Regex Strings (in combination with path string)
1{ 2 "swagger": "2.0", 3 "info": { 4 "title": "Swagger Combine Filter Example", 5 "version": "1.0.0" 6 }, 7 "apis": [ 8 { 9 "url": "http://petstore.swagger.io/v2/swagger.json", 10 "paths": { 11 "exclude": [ 12 ".*\{petId\}.get" 13 ] 14 } 15 }, 16 { 17 "url": "https://api.apis.guru/v2/specs/medium.com/1.0.0/swagger.yaml", 18 "paths": { 19 "include": [ 20 ".*?/publications(/.*)?", 21 "/me.get" 22 ] 23 } 24 } 25 ] 26}
Filtering Parameters
Parameters can be filtered by specifying the path and the parameter name as to exclude
or include
as key/value pairs in paths.parameters
.
1{ 2 "swagger": "2.0", 3 "info": { 4 "title": "Swagger Combine Filter Example", 5 "version": "1.0.0" 6 }, 7 "apis": [ 8 { 9 "url": "http://petstore.swagger.io/v2/swagger.json", 10 "paths": { 11 "parameters": { 12 "exclude": { 13 "/pet/findByStatus": "status" 14 } 15 } 16 } 17 }, 18 { 19 "url": "https://api.apis.guru/v2/specs/medium.com/1.0.0/swagger.yaml", 20 "paths": { 21 "include": [ 22 "/users/{userId}/publications", 23 "/publications/{publicationId}/posts", 24 "/me.get" 25 ], 26 "parameters": { 27 "include": { 28 "/publications/{publicationId}/posts.post": "publicationId" 29 } 30 } 31 } 32 } 33 ] 34}
Base Path
The base path for each Swagger schema can be set by base
:
1{ 2 "swagger": "2.0", 3 "info": { 4 "title": "Basic Swagger Combine Example", 5 "version": "1.0.0" 6 }, 7 "apis": [ 8 { 9 "url": "https://api.apis.guru/v2/specs/medium.com/1.0.0/swagger.yaml" 10 }, 11 { 12 "url": "https://api.apis.guru/v2/specs/deutschebahn.com/betriebsstellen/v1/swagger.json", 13 "paths": { 14 "base": "/bahn" 15 } 16 } 17 ] 18}
Base path definition in Swagger schemas is ignored by default and the processing can be enabled individually by setting useBasePath
. When enabled, the base path and path information is combinded during processing. The option can also be enabled in general (see below). If base
is set, the useBasePath
is ignored.
1{ 2 "swagger": "2.0", 3 "info": { 4 "title": "Swagger Combine simple Rename Example", 5 "version": "1.0.0" 6 }, 7 "apis": [ 8 { 9 "url": "http://petstore.swagger.io/v2/swagger.json", 10 "paths": { 11 "useBasePath": true 12 } 13 }, 14 { 15 "url": "https://api.apis.guru/v2/specs/medium.com/1.0.0/swagger.yaml" 16 } 17 ] 18}
Renaming Paths
Paths can be renamed by specifying the path to rename and the new path name as key/value pairs in paths.rename
.
This will replace each key matched by path with the new value.
1{ 2 "swagger": "2.0", 3 "info": { 4 "title": "Swagger Combine simple Rename Example", 5 "version": "1.0.0" 6 }, 7 "apis": [ 8 { 9 "url": "http://petstore.swagger.io/v2/swagger.json", 10 "paths": { 11 "rename": { 12 "/pet/{petId}": "/pet/alive/{petId}" 13 } 14 } 15 }, 16 { 17 "url": "https://api.apis.guru/v2/specs/medium.com/1.0.0/swagger.yaml" 18 } 19 ] 20}
Paths can also be replaced by regular expressions and functions.
To configure this, it's necessary to use an array like structure instead of an object with key/value pairs to ensure the order of replacements.
In the swagger.json
file only "renaming" and/or a string like regular expression can be used. For regular expression objects or functions the (swagger)json configuration must be generated by javascript and used as input parameter of the swaggerCombine function.
The next example equals the simple example above but used an extended configuration style.
1{ 2 "swagger": "2.0", 3 "info": { 4 "title": "Swagger Combine simple Rename Example", 5 "version": "1.0.0" 6 }, 7 "apis": [ 8 { 9 "url": "http://petstore.swagger.io/v2/swagger.json", 10 "paths": { 11 "rename": [ 12 { 13 "type": "rename", 14 "from": "/pet/{petId}", 15 "to": "/pet/alive/{petId}" 16 } 17 ] 18 } 19 }, 20 { 21 "url": "https://api.apis.guru/v2/specs/medium.com/1.0.0/swagger.yaml" 22 } 23 ] 24}
To change the basePath of all paths a regular expression can be used.
1{ 2 "swagger": "2.0", 3 "info": { 4 "title": "Swagger Combine Rename by regular expression Example", 5 "version": "1.0.0" 6 }, 7 "apis": [ 8 { 9 "url": "http://petstore.swagger.io/v2/swagger.json", 10 "paths": { 11 "rename": [ 12 { 13 "type": "regex", 14 "from": "^\/pet\/(.*)", 15 "to": "/pet/alive/$1" 16 } 17 ] 18 } 19 }, 20 { 21 "url": "https://api.apis.guru/v2/specs/medium.com/1.0.0/swagger.yaml" 22 } 23 ] 24}
An example of dynamic generated configuration and renamings with regular expressions and functions.
1const swaggerJson = { 2 swagger: "2.0", 3 info: { 4 title: "Swagger Combine Rename by regular expression Example", 5 version: "1.0.0" 6 }, 7 apis: [ 8 { 9 url: "http://petstore.swagger.io/v2/swagger.json", 10 paths: { 11 rename: [ 12 { 13 type: "regex", 14 from: /\/pet\/(.*)/, 15 to: "/pet/alive/$1" 16 }, 17 { 18 type: "function", 19 to: (path) => path === "/pet/alive/{petId}" ? "/pet/alive/{petAliveId}" : path 20 } 21 ] 22 } 23 }, 24 { 25 url: "https://api.apis.guru/v2/specs/medium.com/1.0.0/swagger.yaml" 26 } 27 ] 28} 29 30swaggerCombine(swaggerJson) 31...
Renaming Tags
Tags can be renamed in the same manner as paths with simple, object like configuration style, using the tags.rename
field.
1{ 2 "swagger": "2.0", 3 "info": { 4 "title": "Swagger Combine Rename Example", 5 "version": "1.0.0" 6 }, 7 "apis": [ 8 { 9 "url": "http://petstore.swagger.io/v2/swagger.json" 10 }, 11 { 12 "url": "https://api.apis.guru/v2/specs/medium.com/1.0.0/swagger.yaml", 13 "tags": { 14 "rename": { 15 "Users": "People" 16 } 17 } 18 } 19 ] 20}
Renaming Path OperationIds
When merging different swagger definitions there are situations were the operationIds used in these separate swaggers could collide. If this is the case and changing source isn't desired or possible. OperationIds can be renamed by specifying the existing id to rename and the new id as key/value pairs in operationIds.rename
.
This will replace each operationId matched by the provided key with the new value.
1{ 2 "swagger": "2.0", 3 "info": { 4 "title": "Swagger Combine Simple OperationId Rename Example", 5 "version": "1.0.0" 6 }, 7 "apis": [ 8 { 9 "url": "http://petstore.swagger.io/v2/swagger.json", 10 "operationIds": { 11 "rename": { 12 "addPet": "createPet" 13 } 14 } 15 }, 16 { 17 "url": "https://api.apis.guru/v2/specs/medium.com/1.0.0/swagger.yaml" 18 } 19 ] 20}
Adding Tags
Tags can be added to all operations in a schema, using the tags.add
field.
1{ 2 "swagger": "2.0", 3 "info": { 4 "title": "Swagger Combine Rename Example", 5 "version": "1.0.0" 6 }, 7 "apis": [ 8 { 9 "url": "http://petstore.swagger.io/v2/swagger.json", 10 "tags": { 11 "add": [ 12 "pet" 13 ] 14 } 15 }, 16 { 17 "url": "https://api.apis.guru/v2/specs/medium.com/1.0.0/swagger.yaml", 18 "tags": { 19 "add": [ 20 "medium" 21 ] 22 } 23 } 24 ] 25}
Renaming Security Definitions
Security definitions can be renamed like paths (simple) and tags in the securityDefinitions.rename
field. All usages of the security definition in the paths are renamed as well.
1{ 2 "swagger": "2.0", 3 "info": { 4 "title": "Swagger Combine Rename Example", 5 "version": "1.0.0" 6 }, 7 "apis": [ 8 { 9 "url": "http://petstore.swagger.io/v2/swagger.json", 10 "securityDefinitions": { 11 "rename": { 12 "api_key": "KEY" 13 } 14 } 15 }, 16 { 17 "url": "https://api.apis.guru/v2/specs/medium.com/1.0.0/swagger.yaml" 18 } 19 ] 20}
Path Security
Security can be specified per path using the paths.security
field.
1{ 2 "swagger": "2.0", 3 "info": { 4 "title": "Swagger Combine Security Example", 5 "version": "1.0.0" 6 }, 7 "apis": [ 8 { 9 "url": "http://petstore.swagger.io/v2/swagger.json", 10 "paths": { 11 "security": { 12 "/store/order": { 13 "petstore_auth": [ 14 "write:pets", 15 "read:pets" 16 ] 17 }, 18 "/store/order/{orderId}.delete": { 19 "petstore_auth": [ 20 "write:pets", 21 "read:pets" 22 ] 23 } 24 } 25 } 26 }, 27 { 28 "url": "https://api.apis.guru/v2/specs/medium.com/1.0.0/swagger.yaml" 29 } 30 ] 31}
Authentication & Request Headers
To retrieve Swagger schemas that are access protected, basic auth information (username and password) or any headers to be sent with the http request can be specified:
1{ 2 "swagger": "2.0", 3 "info": { 4 "title": "Swagger Combine Authentication Example", 5 "version": "1.0.0" 6 }, 7 "apis": [ 8 { 9 "url": "http://petstore.swagger.io/v2/swagger.json", 10 "resolve": { 11 "http": { 12 "auth": { 13 "username": "admin", 14 "password": "secret12345" 15 } 16 } 17 } 18 }, 19 { 20 "url": "https://api.apis.guru/v2/specs/medium.com/1.0.0/swagger.yaml", 21 "resolve": { 22 "http": { 23 "headers": { 24 "authorization": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6ImFkbWluIiwiYWRtaW4iOnRydWV9.44lJS0jlltzcglq7vgjXMXYRTecBxseN3Dec_LO_osI" 25 } 26 } 27 } 28 }, 29 { 30 "url": "https://api.apis.guru/v2/specs/deutschebahn.com/betriebsstellen/v1/swagger.json", 31 "resolve": { 32 "http": { 33 "headers": { 34 "authorization": "Basic YWRtaW46c2VjcmV0MTIz" 35 } 36 } 37 } 38 } 39 ] 40}
For all possible resolve options have a look at the documentation of json-schema-ref-parser.
API
swaggerCombine(config, [options], [callback])
Returns promise
with dereferenced and combined schema.
config string|object
URL/path to config schema file or config schema object.
Default:
docs/swagger.json
options object
(optional)
-
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. -
continueOnConflictingPaths -
boolean
Continue if Swagger schemas have conflicting paths (default:
false
). An error is only thrown if conflicting paths also have conflicting operations (e.g. if two Swagger schemas both have/pets.get
and/pets.get
defined).
See JSON Schema $Ref Parser Options for a complete list of options.
-
useBasePath -
boolean
(default: false)The base path defintion in Swagger schemas is ignored by default. To respect the base path during combination, configure
useBasePath
in general or for individual Swagger schemas. -
includeGlobalTags -
boolean
(default: false)Combine global tags (set on the root level of the schemas) as well.
callback function(err, combinedSchema)
(optional)
Callback with error and the dereferenced and combined schema.
swaggerCombine.middleware(config, [options])
Returns function(req, res, next)
for usage as middleware.
config string|object
see above
options object
(optional)
see above
swaggerCombine.middlewareAsync(config, [options])
Returns a promise
yielding a function(req, res, next)
for usage as middleware.
config string|object
see above
options object
(optional)
see above
No vulnerabilities found.
Reason
no dangerous workflow patterns detected
Reason
no binaries found in the repo
Reason
license file detected
Details
- Info: project has a license file: LICENSE:0
- Info: FSF or OSI recognized license: MIT License: LICENSE:0
Reason
Found 3/16 approved changesets -- score normalized to 1
Reason
0 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0
Reason
detected GitHub workflow tokens with excessive permissions
Details
- Warn: no topLevel permission defined: .github/workflows/ci.yml:1
- Info: no jobLevel write permissions found
Reason
dependency not pinned by hash detected -- score normalized to 0
Details
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:24: update your workflow using https://app.stepsecurity.io/secureworkflow/maxdome/swagger-combine/ci.yml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:26: update your workflow using https://app.stepsecurity.io/secureworkflow/maxdome/swagger-combine/ci.yml/master?enable=pin
- Warn: third-party GitHubAction not pinned by hash: .github/workflows/ci.yml:34: update your workflow using https://app.stepsecurity.io/secureworkflow/maxdome/swagger-combine/ci.yml/master?enable=pin
- Warn: npmCommand not pinned by hash: .github/workflows/ci.yml:31
- Info: 0 out of 2 GitHub-owned GitHubAction dependencies pinned
- Info: 0 out of 1 third-party GitHubAction dependencies pinned
- Info: 0 out of 1 npmCommand dependencies pinned
Reason
no effort to earn an OpenSSF best practices badge detected
Reason
security policy file not detected
Details
- Warn: no security policy file detected
- Warn: no security file to analyze
- Warn: no security file to analyze
- Warn: no security file to analyze
Reason
project is not fuzzed
Details
- Warn: no fuzzer integrations found
Reason
SAST tool is not run on all commits -- score normalized to 0
Details
- Warn: 0 commits out of 21 are checked with a SAST tool
Reason
24 existing vulnerabilities detected
Details
- Warn: Project is vulnerable to: GHSA-67hx-6x53-jw92
- Warn: Project is vulnerable to: GHSA-qwcr-r2fm-qrc7
- Warn: Project is vulnerable to: GHSA-grv7-fg5c-xmjg
- Warn: Project is vulnerable to: GHSA-pxg6-pf52-xh8x
- Warn: Project is vulnerable to: GHSA-h452-7996-h45h
- Warn: Project is vulnerable to: GHSA-3xgq-45jj-v275
- Warn: Project is vulnerable to: GHSA-gxpj-cx7g-858c
- Warn: Project is vulnerable to: GHSA-rv95-896h-c2vc
- Warn: Project is vulnerable to: GHSA-qw6h-vgh9-j6wx
- Warn: Project is vulnerable to: GHSA-4q6p-r6v2-jvc5
- Warn: Project is vulnerable to: GHSA-9c47-m6qq-7p4h
- Warn: Project is vulnerable to: GHSA-p6mc-m468-83gw
- Warn: Project is vulnerable to: GHSA-f8q6-p94x-37v3
- Warn: Project is vulnerable to: GHSA-xvch-5gv4-984h
- Warn: Project is vulnerable to: GHSA-qrpm-p2h7-hrv2
- Warn: Project is vulnerable to: GHSA-mwcw-c2x4-8c55
- Warn: Project is vulnerable to: GHSA-9wv6-86v2-598j
- Warn: Project is vulnerable to: GHSA-rhx6-c78j-4q9w
- Warn: Project is vulnerable to: GHSA-hrpp-h998-j3pp
- Warn: Project is vulnerable to: GHSA-c2qf-rxjj-qqgw
- Warn: Project is vulnerable to: GHSA-m6fv-jmcg-4jfg
- Warn: Project is vulnerable to: GHSA-cm22-4g7w-348p
- Warn: Project is vulnerable to: GHSA-qgmg-gppg-76g5
- Warn: Project is vulnerable to: GHSA-xx4c-jj58-r7x6
Score
2.9
/10
Last Scanned on 2024-12-16
The Open Source Security Foundation is a cross-industry collaboration to improve the security of open source software (OSS). The Scorecard provides security health metrics for open source projects.
Learn More