How do I combine multiple OpenAPI 3 specification files together?

Question

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?

Answer 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

Answer 2

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. Use Codegen 3.x with openapi: 3.0.x files and Codegen 2.x with swagger: '2.0' files.

CLI example (line breaks added for readability):

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

The input file (-i) can be a local file or an URL.

Use -l openapi-yaml to output YAML or -l openapi to output JSON. In Codegen 2.x, use -l swagger-yaml for YAML and -l swagger for JSON.

-DoutputFile is optional, the default file name is openapi.yaml / openapi.json in Codegen 3.x and swagger.yaml / swagger.json in Codegen 2.x.