How do I combine multiple OpenAPI 3 specification files together?
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 $ref
s 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
.
Related videos on Youtube
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, 2022Comments
-
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 over 3 yearsI 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 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. over 2 yearsFinally someone who combines multiple specifications, not "merges" the
$ref
s! Thank you so much 🙏🏻 -
Iter Ator over 2 yearsSpeccy is not actively maintained anymore
-
chaseisabelle over 1 yearSo far, this tool is pretty dope!
echo '{"inputs":[{"inputFile":"./lib.yaml"},{"inputFile":"./api.yaml"}],"output":"./v1.json"}' > ${PWD}/docs/merge.json
docker run --rm -ti -v ${PWD}/docs:/docs -w /docs 3apaxicom/npx openapi-merge-cli --config ./merge.json