swagger-merger

Merge multiple swagger files into a swagger file, support JSON/YAML.

Downloads in past

Stats

StarsIssuesVersionUpdatedCreatedSize
swagger-merger
11751.5.410 months ago6 years agoMinified + gzip package size for swagger-merger in KB

Readme

┌─┐┬ ┬┌─┐┌─┐┌─┐┌─┐┬─┐   ┌┬┐┌─┐┬─┐┌─┐┌─┐┬─┐
└─┐│││├─┤│ ┬│ ┬├┤ ├┬┘───│││├┤ ├┬┘│ ┬├┤ ├┬┘
└─┘└┴┘┴ ┴└─┘└─┘└─┘┴└─   ┴ ┴└─┘┴└─└─┘└─┘┴└─

Greenkeeper badge Node.js(≥12.22) CI Coverage Status Standard - JavaScript Style Guide License
Merge multiple related files from a input swagger file, Write to a output swagger file.
Support JSON/YAML.

NPM
swagger-merger status

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.


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
```
```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
  1. The output swagger.json is same as the expected heroku-pets.json.
  2. The output swagger.yaml is similar to the expected heroku-pets.yaml.

echo

  • Base on official swagger example
  • Modify to support for $ref tags

Go to example/echo
  1. The output swagger.json is same as the expected echo.json.
  2. The output swagger.yaml is similar to the expected echo.yaml.

petstoresimple

  • Base on official swagger example
  • Modify to support for $ref# tags

Go to example/petstore_simple
  1. The output swagger.json is same as the expected petstore_simple.json.
  2. The output swagger.yaml is similar to the expected petstore_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
  1. The output swagger.json is same as the expected petstore_simple.json.
  2. The output swagger.yaml is similar to the expected petstore_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.

License

MIT