windomz / swagger-merger Goto Github PK

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

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

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

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

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

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

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.

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.

Your Greenkeeper Bot 🌴

Love the package, it would be great to see it support references to sub elements of a file. Documentation:

https://swagger.io/docs/specification/using-ref/

example

$ref: '../document.json#/myElement'

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?

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

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?

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.

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!

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 ?

If you merge the attached sample.yaml, "#/definitions/Code" is not expanded.

sample.zip

Regards

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

I tried using this to process a swagger.json file which had refs to a "submodels.json" file. After it is done, the refs are exactly the same.

Reference:

# main.yaml
paths:
  $ref#reconciliation: "./reconciliation.yaml"
...

# reconciliation.yaml
/mypath/{id}:
 post:
...

result

# swagger.yaml
paths:
  '/mypath/{id}':
 post:
...

The quotes around the path seem to be invalid.

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

pets.yaml

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

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

I get error: Maximum call stack size exceeded when using v1.5.1+, but it's ok with v1.4.3 and v1.5.0.

This is an example:

paths:
  $ref#users-api: https://api.eraofhealth.com/users-api

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

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

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

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

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.

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": "..."
  }
}

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

Regards
Humpf

Switched to this package from openapi-merger in hope for better, more predictable support of references.

Let's say, you want to have a file per path, like this:

paths:
  /users/{id}/profile:
    $ref: "./paths/users/{id}/profile.yml"

This is legal, as { and } are legal in Linux paths, and in YAML keys and values. However, after running swagger-merger, the result is just that same $ref inserted verbatim, without resolving it to the contents of the referenced file.

Looks like curly braces are not supported, which is quite unpredictable.

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

Or when do you plan to support merging of multiple independent yaml files? i.e. my cli should accept multiple yaml files or *.yaml as input and do the job.