┌─┐┬ ┬┌─┐┌─┐┌─┐┌─┐┬─┐ ┌┬┐┌─┐┬─┐┌─┐┌─┐┬─┐
└─┐│││├─┤│ ┬│ ┬├┤ ├┬┘───│││├┤ ├┬┘│ ┬├┤ ├┬┘
└─┘└┴┘┴ ┴└─┘└─┘└─┘┴└─ ┴ ┴└─┘┴└─└─┘└─┘┴└─
Merge multiple related files from a input swagger file, Write to a output swagger file.
Support JSON/YAML.
Features
- x Merge multiple swagger files into a swagger file.
- x $ref - A tag, include a single-level of swagger file.
- x $ref# - A tag, include a multi-level of swagger file.
- x Support JSON/YAML swagger files(
.json
/.yaml
/.yml
). - x CLI - Command line interface.
Usage
$ref
Includes a single-level of swagger file.
- Official standards
- Recommended, universal
For
yaml
example:$ref: "./host.yaml"
parameters:
- $ref: "name.yaml"
- $ref: "./year.yaml"
- $ref: "age.yaml#/alex/son"
remote:
$ref: "https://raw.githubusercontent.com/WindomZ/swagger-merger/remote.yaml#/name"
responses:
$ref: "./responses.yaml#/post"
$ref#
Includes a multi-level of swagger file.
- Non-standard, suggest you use it for yourself
- Instead of
$ref
, can be used side by side and not an array
For
yaml
example:paths:
$ref#pets: "./paths/pets.yaml"
$ref#pets-id: "./paths/pets-id.yaml"
paths-url:
$ref#paths: "https://raw.githubusercontent.com/WindomZ/swagger-merger/master/test/no_ext_json"
Output
yaml
:paths:
/pets:
hello: world
/pets/{id}:
good: bye
paths-url:
/pets:
hello: world
/pets/{id}:
good: bye
CLI
How to use?
$ swagger-merger -h
Usage: swagger-merger [-h] [-v] [-c] [-o file] <-i file | file>
Merge multiple swagger files into a swagger file, just support JSON/YAML.
Options:
-h, --help output usage information
-V, --version output the version number
-i, --input <file> input a main/entry JSON/YAML swagger file
-o, --output <file> output a merged JSON/YAML swagger file, default is `swagger.*`
-c, --compact compact JSON/YAML format string
--debug debug mode, such as print error tracks
Easy to use.
swagger-merger -i in.yaml # Merge in.yaml into swagger.yaml
swagger-merger -i in.yaml -o out.yaml # Merge in.yaml into out.yaml
swagger-merger -i in.yaml -o out.yaml -c # Merge in.yaml into out.yaml and compress it
swagger-merger -i in.yaml -o out.json # Merge in.yaml into out.json
swagger-merger -i in.json # Merge in.json into swagger.json
swagger-merger -i in.json -o out.json # Merge in.json into out.json
swagger-merger -i in.json -o out.json -c # Merge in.json into out.json and compress it
swagger-merger -i in.json -o out.yaml # Merge in.json into out.yaml
Module
How to use?
npm install swagger-merger
#!/usr/bin/env node
const swaggerMerger = require('swagger-merger')
swaggerMerger.merge({
input: 'index.json',
output: 'swagger.json',
compact: false
}).catch(e => {
console.error(e)
})
Install
npm install swagger-merger -g
Examples
It would be more helpful to see these examples.
Open the terminal, choose one of the following ways:
```bash
npm install
npm run test
```
```bash
yarn
yarn run test
```
- swagger-merger) (installed, go to each examples)
```bash
swagger-merger -i index.yaml
swagger-merger -i index.json
```
Then, these examples may help you:heroku-pets
- Official swagger example
- No modification
Go to
example/heroku-pets
- The output
swagger.json
is same as the expectedheroku-pets.json
. - The output
swagger.yaml
is similar to the expectedheroku-pets.yaml
.
echo
- Base on official swagger example
- Modify to support for $ref tags
Go to
example/echo
- The output
swagger.json
is same as the expectedecho.json
. - The output
swagger.yaml
is similar to the expectedecho.yaml
.
petstoresimple
- Base on official swagger example
- Modify to support for $ref# tags
Go to
example/petstore_simple
- The output
swagger.json
is same as the expectedpetstore_simple.json
. - The output
swagger.yaml
is similar to the expectedpetstore_simple.yaml
.
petstoredomain
A way of using $ref instead of $ref#, and better compatibility.
- Same as petstoresimple
- Modify to support for $ref tags
- Modify to support for multiple levels schema
Go to
example/petstore_domain
- The output
swagger.json
is same as the expectedpetstore_simple.json
. - The output
swagger.yaml
is similar to the expectedpetstore_simple.yaml
.
Contributing
Welcome to pull requests, report bugs, suggest ideas and discuss swagger-merger, i would love to hear what you think about swagger-merger on issues page.If you like it then you can put a :star: on it.