How do I combine multiple OpenAPI 3 specification files together?

28,313

Solution 1

One way to do this is to use the open-source project speccy.

Open the terminal and install speccy by running (requires Node.js):

npm install speccy -g

Then run:

speccy resolve path/to/spec.yaml -o spec-output.yaml

Solution 2

I wrote a quick tool to do this recently. I call it openapi-merge. There is a library and an associated CLI tool:

In order to use the CLI tool you just write a configuration file and then run npx openapi-merge-cli. The configuration file is fairly simple and would look something like this:

{
  "inputs": [
    {
      "inputFile": "./gateway.swagger.json"
    },
    {
      "inputFile": "./jira.swagger.json",
      "pathModification": {
        "stripStart": "/rest",
        "prepend": "/jira"
      }
    },
    {
      "inputFile": "./confluence.swagger.json",
      "disputePrefix": "Confluence",
      "pathModification": {
        "prepend": "/confluence"
      }
    }
  ], 
  "output": "./output.swagger.json"
}

For more details, see the README on the NPM package.

Solution 3

Most OpenAPI tools can work with multi-file OpenAPI definitions and resolve $refs dynamically.

If you specifically need to get a single resolved file, Swagger Codegen can do this. Below are usage examples for the command-line version of Swagger Codegen. The input file (-i) can be a local file or a URL.

Note: Line breaks are added for readability.

OpenAPI 3.0 example

Use Codegen 3.x to resolve OpenAPI 3.0 files:

java -jar swagger-codegen-cli-3.0.34.jar generate
     -l openapi-yaml
     -i ./path/to/openapi.yaml
     -o ./OUT_DIR
     -DoutputFile=output.yaml

-l openapi-yaml outputs YAML, -l openapi outputs JSON.

-DoutputFile is optional, the default file name is openapi.yaml / openapi.json.

OpenAPI 2.0 example

Use Codegen 2.x to resolve OpenAPI 2.0 files (swagger: '2.0'):

java -jar swagger-codegen-cli-2.4.27.jar generate
     -l swagger-yaml
     -i ./path/to/openapi.yaml
     -o ./OUT_DIR
     -DoutputFile=output.yaml

-l swagger-yaml outputs YAML, -l swagger outputs JSON.

-DoutputFile is optional, the default file name is swagger.yaml / swagger.json.

Share:
28,313

Related videos on Youtube

heitortsergent
Author by

heitortsergent

Community Content Lead at Runscope, former developer evangelist at SendGrid and Azuki, brazilian developer/game developer for mobile devices. JavaScript, Objective-C, C#/XNA, Java, AS3/Flashpunk, and a little C++.

Updated on July 09, 2022

Comments

  • heitortsergent
    heitortsergent over 1 year

    I want to combine an API specification written using the OpenAPI 3 spec, that is currently divided into multiple files that reference each other using $ref. How can I do that?

  • asceta
    asceta over 3 years
    I personally could not figure out an option to "combine" or "merge" multiple input definitions, using codegen; could you provide an example? The -i swtich accepts single input - event passing multiple values (-i def1.json -i def2.json) does not work
  • Helen
    Helen over 3 years
    @asceta this Q&A is about the situation when you have one "main" API definition file that uses $ref to reference external definitions. If you mean you have two different API definitions (with different sets of endpoints, schemas, etc.) that you want to merge, it's a different use case, and you should ask a new question.
  • Rémi B.
    Rémi B. over 2 years
    Finally someone who combines multiple specifications, not "merges" the $refs! Thank you so much 🙏🏻
  • Iter Ator
    Iter Ator over 2 years
    Speccy is not actively maintained anymore
  • chaseisabelle
    chaseisabelle over 1 year
    So far, this tool is pretty dope! echo '{"inputs":[{"inputFile":"./lib.yaml"},{"inputFile":"./api.y‌​aml"}],"output":"./v‌​1.json"}' > ${PWD}/docs/merge.json docker run --rm -ti -v ${PWD}/docs:/docs -w /docs 3apaxicom/npx openapi-merge-cli --config ./merge.json