Code Monkey home page Code Monkey logo

swagger-merger's Introduction

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

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

  • Merge multiple swagger files into a swagger file.
  • $ref - A tag, include a single-level of swagger file.
  • $ref#* - A tag, include a multi-level of swagger file.
  • Support JSON/YAML swagger files(.json/.yaml/.yml).
  • 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:

  • npm

    npm install
    npm run test
  • yarn

    yarn
    yarn run test
  • swagger-merger (installed, go to each examples)

    swagger-merger -i index.yaml
    swagger-merger -i index.json

Then, these examples may help you:

  • 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.
  • 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.
  • 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.

A way of using $ref instead of $ref#*, and better compatibility.

  • Same as petstore_simple
  • 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 ⭐ on it.

License

MIT

swagger-merger's People

Contributors

brinley avatar cm-iwata avatar dependabot[bot] avatar greenkeeper[bot] avatar mfcollins3 avatar ohbarye avatar windomz avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar

swagger-merger's Issues

List of definitions outputs an array

I try to merge several Swagger files into one but facing the problem that the resulting Swagger file reflects an list of definitions as an array instead of a combined object, is this by design or is it a bug? The OpenAPI 2.0 specifies that the "definitions" block should be an object.

Config:

definitions:
  - $ref: "./file1.json#definitions"
  - $ref: "./file2.json#definitions"

Actual output:

{
  "definitions": [
  {
    "file1Definition1": "...",
    "file1Definition2": "..."
  },
  {
    "file2Definition1": "...",
    "file2Definition2": "..."
  }
  ]
}

Expected output:

{
  "definitions": 
 {
    "file1Definition1": "...",
    "file1Definition2": "...",
    "file2Definition1": "...",
    "file2Definition2": "..."
  }
}

Replacing the input swagger file with the output swagger file (not merging)

If I run the command

swagger-merger -i petstore.json -o myswagger.json

Expected

The content of petstore.json gets merged/combined into content of myswagger.json, meaning myswagger.json should have both.

Issue

The content of petstore.json overwrites/replaces the content of myswagger.json, meaning the content of myswagger.json is lost!

--debug option does not work

Hi,
It seems that the cause is on options.parent.debug instead of options.debug in swagger-merger.js

Regards
Humpf

An in-range update of nyc is breaking the build 🚨

The devDependency nyc was updated from 13.1.0 to 13.2.0.

🚨 View failing branch.

This version is covered by your current version range and after updating it in your project the build failed.

nyc is a devDependency of this project. It might not break your production code or affect downstream projects, but probably breaks your build or test tools, which may prevent deploying or publishing.

Status Details
  • continuous-integration/travis-ci/push: The Travis CI build failed (Details).
  • coverage/coveralls: First build on greenkeeper/nyc-13.2.0 at 97.376% (Details).

Commits

The new version differs by 17 commits.

  • 29e6f5e chore(release): 13.2.0
  • e95856c chore: Update dependencies. (#978)
  • 921d386 fix: Create directory for merge destination. (#979)
  • df2730d feat: Option Plugins (#948)
  • 35cd49a feat: document the fact that cacheDir is configurable (#968)
  • ff834aa feat: avoid hardcoded HOME for spawn-wrap working dir (#957)
  • 35710b1 build: move windows tests to travis (#961)
  • 93cb5c1 tests: coverage for temp-dir changes (#964)
  • d566efe test: stop using LAZY_LOAD_COUNT (#960)
  • f23d474 chore: update stale bot config with feedback (#958)
  • 62d7fb8 chore: slight tweak to position of test
  • 28b6d09 fix: missing command temp-directory (#928)
  • 40afc5f fix: nyc processing files not covered by include when all is enabled. (#914)
  • ba22a26 docs(readme): Update to reflect .nycrc.json support (#934)
  • 2dbb82d chore: enable probot-stale

There are 17 commits in total.

See the full diff

FAQ and help

There is a collection of frequently asked questions. If those don’t help, you can always ask the humans behind Greenkeeper.


Your Greenkeeper Bot 🌴

Inherited base model schema not being included in final output file

Hi,

I have the following:
path.yml

get:
    tags:
    - "Tag One"
    responses:
      '200':
          description: Just an example of includes
          content:
              application/json:
                  schema:
                      type: array
                      items:
                          $ref: './schema.yml#/put'

schema.yml:

base:
    type: object
    properties:
        propOne:
            type: string
            example: "Example String"
        propTwo:
            type: integer
            example: 0

put:
    allOf:
    - $ref: '#/base'
    - type: object
    properties:
        undelete:
            type: boolean
            example: false
        reprocess:
            type: boolean
            example: false

The merger doesn't pull in the base properties which results in the output file referencing something that doesn't exist:

  "paths": {
    "/some/path": {
      "get": {
        "tags": [
          "Tag One"
        ],
        "responses": {
          "200": {
            "description": "Just an example of includes",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "allOf": [
                      {
                        "$ref": "#/base"
                      },
                      {
                        "type": "object"
                      }
                    ],
                    "properties": {
                      "undelete": {
                        "type": "boolean",
                        "example": false
                      },
                      "reprocess": {
                        "type": "boolean",
                        "example": false
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }

I've included the example files to help solve this issues.

Thanks.

example.zip

requires file extension

expected

referencing a remote yaml or json file with or without a file extension works the same

actual

if the remote file doesnt have a file extension the cli replaces the reference with undefined instead of dereferencing the remote file

merger function return dump

Right now, it appears that the merger function returns some sort of promise instead of the dump from the resulting merge. It would be nice if I where able to programmatically retrieve the dump without having to write to a file in the process.

Am I missing an important reason as to why this promise is returned instead of the dump? Is there I way I'm missing to get the dump without writing to a file?

e.g. I would like to be able to use this library like this:

//Merge yaml files
const spec = merger({
  input: './src/__docs__/index.yml',
  compact: false
})

//Feed directly into swagger
router.get("/", koaSwagger({
  routePrefix: "/docs",
  specPrefix: "/docs/spec",
  swaggerOptions: {spec}
}))

Edit: for now I forked this repo and frankensteined this functionality in, I won't pull request it because all other features of the repo besides what I'm specifically doing is untested and I have reason to believe it won't work at all haha. Thanks for making this project, it helps tidy up code a lot! After using this it feels like $ref#* should be a feature of swagger/openapi officially

Support for typescript

Does this module support typescript?
Importing show warning on my codebase because

Could not find a declaration file for module 'swagger-merger'. '/Users/song/Xendit/nex-api/node_modules/swagger-merger/index.js' implicitly has an 'any' type.
  Try `npm i --save-dev @types/swagger-merger` if it exists or add a new declaration (.d.ts) file containing `declare module 'swagger-merger';`ts(7016)

npm i --save-dev @types/swagger-merger results in NOT FOUND

reference remote files

i would like to merge a remote file like
$ref: "https://raw.githubusercontent.com/swagger-api/swagger-codegen/master/modules/swagger-codegen/src/test/resources/2_0/petstore.yaml" into my specification and also use the url#/subobject syntax on it like:
$ref: "https://raw.githubusercontent.com/swagger-api/swagger-codegen/master/modules/swagger-codegen/src/test/resources/2_0/petstore.yaml#/securityDefinitions"
Is it possible to implement this for swagger-merger?

Dockerfile should build image from source

Dockerfile which was added in #69 and #70 installs swagger-merger NPM package:

RUN npm install -g swagger-merger watch

It is probably the most efficient way to build a Docker image around swagger-merger, but it leaves a lot to be desired. For example, how would someone build a swagger-merger Docker image with the latest features from GitHub repo, from a branch, from a fork, with changes from someone's local working directory?

There should be a Dockerfile that allows building image from source code checkout instead of relying on NPM.

Merge instead of replace

Usecase: Where I have a legacy swagger.json. And now I just want to add new paths/def using swagger-merger instead of editing old file.

Example:

// apis.swagger.json
{
  "swagger": "2.0",
  "info": {
    "version": "1.0.0",
    "title": "Echo",
    "description": "#### Echos back every URL, method, parameter and header\nFeel free to make a path or an operation and use **Try Operation** to test it. The echo server will\nrender back everything.\n"
  },
  "schemes": [
    "http"
  ],
  "$ref": "./host.yaml",
  "basePath": "/echo",
  "paths": {
    "/": {
      "get": {
        "responses": {
          "$ref": "./responses.json#/components/root/get"
        }
      },
      "post": {
        "responses": {
          "$ref": "./responses.json#/components/root/post"
        },
        "parameters": [
          {
            "$ref": "./name.json"
          },
          {
            "$ref": "./year.json"
          }
        ]
      }
    }
  }
}
// index.json
{
    "$ref": "apis.swagger.json",
    "paths": {
        "/test-path/{id}": {
            "parameters": [
                {
                    "$ref": "./id.json"
                }
            ],
            "get": {
                "responses": {
                    "$ref": "./responses.json#/components/test-path"
                }
            }
        }
    }
}

Expected:

{
  "swagger": "2.0",
  "info": {
    "version": "1.0.0",
    "title": "Echo",
    "description": "#### Echos back every URL, method, parameter and header\nFeel free to make a path or an operation and use **Try Operation** to test it. The echo server will\nrender back everything.\n"
  },
  "schemes": [
    "http"
  ],
  "$ref": "./host.yaml",
  "basePath": "/echo",
  "paths": {
    "/": {
      "get": {
        "responses": {
          "$ref": "./responses.json#/components/root/get"
        }
      },
      "post": {
        "responses": {
          "$ref": "./responses.json#/components/root/post"
        },
        "parameters": [
          {
            "$ref": "./name.json"
          },
          {
            "$ref": "./year.json"
          }
        ]
      }
    },
    "/test-path/{id}": {
      "parameters": [
        {
          "$ref": "./id.json"
        }
      ],
      "get": {
        "responses": {
          "$ref": "./responses.json#/components/test-path"
        }
      }
    }
  }
}

Is there anyway to achieve this?

Merging content from files does not working well on a special situation

I am having the following files:

testBug.zip

The idea is: in the command description file, for some reasons, the same uri is expanded into 2 different path locations (one is for global access and will be included in one documentation and the second one is for admin and will be included in the admin documentation along with the one from global).

The idea is when merging the files swagger-merger -i ./test-spec.json -o ./test.json, the resulted file contains just one command for the given endpoint (jut put without get) if the same endpoint is found 2 times.
It does not work well even if I change the tags and I name them differently.

If you need more details, just let me know. This feature saves us on big projects with lots of api endpoints to manage in a documentation which is splitted into different small files for easily management.

Regards

Run inside JavaScript

How can i run ir inside javascript code not user child_process exec and not install globally?

const swaggerMerger = require('swagger-merger');
swaggerMerger ....

NodeJS version requirement

I'm not a JS expert but in your package.json you require:

"engines": {
    "node": ">= 0.6.x"
}

I'm using Debian Stretch with default node version: v4.8.2 (which has no full ES6 Support) but you seem to use ES6 features in this project.

You should fix the required version in package.json to give everyone who uses an outdated version of node a hint why he can't install swagger-merger and avoid that he is getting an error like this:

/usr/local/lib/node_modules/swagger-merger/node_modules/fmtconv/lib/converter.js:19
function fmtconv (input, output, compact = false) {
                                         ^

SyntaxError: Unexpected token =
    at exports.runInThisContext (vm.js:53:16)
    at Module._compile (module.js:373:25)
    at Object.Module._extensions..js (module.js:416:10)
    at Module.load (module.js:343:32)
    at Function.Module._load (module.js:300:12)
    at Module.require (module.js:353:17)
    at require (internal/module.js:12:17)
    at Object.<anonymous> (/usr/local/lib/node_modules/swagger-merger/node_modules/fmtconv/lib/fmtconv.js:6:19)
    at Module._compile (module.js:409:26)
    at Object.Module._extensions..js (module.js:416:10)

I think at least v6.0.0 should be required.

debug not working properly

I'm trying to run a shell script to build a documentation. When I do this I get an error:

xxxxxxxx/node_modules/swagger-merger/bin/swagger-merger.js:27
input: options.input || file || '',
^

TypeError: Cannot read property 'input' of undefined
at Command.program.version.usage.description.option.option.option.option.action (/xxxxxxxxxx/node_modules/swagger-merger/bin/swagger-merger.js:27:22)
at Command.listener (/xxxxxxxxx/node_modules/commander/index.js:315:8)
at Command.emit (events.js:182:13)
at Command.parseArgs (/xxxxxxxxxxx/node_modules/commander/index.js:668:12)
at Command.parse (/xxxxxxxxxxxxx/node_modules/commander/index.js:474:21)
at Object. (/xxxxxxxxxxxxxx/node_modules/swagger-merger/bin/swagger-merger.js:35:9)
at Module._compile (internal/modules/cjs/loader.js:722:30)
at Object.Module._extensions..js (internal/modules/cjs/loader.js:733:10)
at Module.load (internal/modules/cjs/loader.js:620:32)
at tryModuleLoad (internal/modules/cjs/loader.js:560:12)

If I run the command separately I get:
swagger-merger --debug -i src/swagger/main.yml
Unexpected token [ in JSON at position 3502

what it's not very helpful without the proccessed file. i have like 200

node: 11.3.0
npm: 6.4.1

Thanks in advance

$ref tag side by side with objects

Hi @WindomZ, thank you for this package,
i encountered unresolved paths, if they are on the same level as other objects.
For example my swagger yaml definitions are built like the following:

definitions:
  options:
    type: "object"
    properties:
     ...
  next_object:
    type:...

if i want to include some external definitions i do it like this:

definitions:
  $ref: "./defs.yaml#/definitions"
  options:
    type: "object"
    properties:
      ...
  next_object:
    type:...

which is not resolving the path

but if i only have the path in definitions, the path gets resolved:

definitions:
  $ref: "./defs.yaml#/definitions"

is it possible to do this somehow ?

How about adding Dockerfile and publishing images on DockerHub?

Hello 👋
As the title says, how about adding Dockerfile and publishing images on DockerHub?

I use swagger-merger with Docker. It compels me to write a Dockerfile for that but it brings a benefit to reuse this library with ease.

I've already created an example repository https://github.com/ohbarye/swagger-merger-docker and published Docker image on https://hub.docker.com/r/ohbarye/swagger-merger though, I think the Dockerfile can be in this repository (if you're willing so).

If you don't like this idea, feel free to close this issue. I know that managing a Docker image needs additional works and a maintainer might suffer.

Referencing a value inside a yaml file

Given the following input file: in.yaml

description:
    $ref: ./desc.yaml#/description

And the following referenced file: desc.yaml:

description: this is a value

When I merge the input file using swagger-merger -i in.yaml -o out.yaml

Then I receive the following error: Unexpected token } in JSON at position 33

Windows support for splitReference method

Hi WindomZ,

First of all, nice work :)
...And then the issue:

On Windows, when you evaluate path.join() the structure will be converted
./responses.yaml#/components/root/get -> .\responses.yaml#\components\root\get

This is Ok, if you want to locate the file, but the splitReference method gets the \components\root\get string so this code is not enugh

if (hashtag.startsWith('/')) {
          hashtag = hashtag.slice(1)
        }

I would suggest place these 2 lines before this:

//in case of windows operating system
hashtag = hashtag.replace(/\\/g, "/")

Regards, Adam

Awesome

Thank you for creating this package, it saves me a lot of time.

OAS 3 support?

seems to work for open api 3. Is it "officially supported" or did I just get lucky?

Can't merge definition that include {}

I want to merge these files

swagger.yaml

...
paths:
  /pets/{id}:
    $ref: "./pets.yaml#/paths/~1pets~1{id}"

pets.yaml

paths:
  /pets/{id}:
    get: ....
    delete: ....

This file structure is helpful for maintenance definition file with some IDE.

I use IntelliJ.
InteliJ can render these files Individually like this.

swagger.yaml
image

pets.yaml
image
I can maintenance pets.yaml with same API path in preview screen.

But, swagger-merger will skip merge definition that include {}.
So, I can't use /paths/~1pets~1{id} for api definition's key

I tried fix this regular expression

return doc.replace(/\s*("\$ref")( *):( *)"[^"{}]+"\s*/gm, s => {

to

return doc.replace(/\s*("\$ref")( *):( *)"[^"]+"\s*/gm, s => {

Them, I can merge these definitions.
But, I'm not sure if this fix is correct.

I'm sorry I'm not good at English

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.