How to merge multiple OpenAPI specifications?

Question

I'm digging here around trying to find a solution, how to merge several OpenApi v3 component definitions in one file.

Let's imagine a situation:

1. You decided to split your OpenApi into multiple files in different folders. (see image below)
2. Now you need to combine all your components.v1.yaml into a single schema (i named it blueprint.v1.yaml). Usually, I use swagger-cli to merge all $ref dependencies, but now it's not a case, because I can not refer to the whole components/schemas object list
3. And use it to build a single OpenApi file with all fields filled: info, components, paths and so on with a swagger-cli bundle tool.

So, the question is - how to reuse already defined component blocks (files called components.v1.yaml) in my blueprint.v1.yaml file?

P.S. Every components.v1.yaml looks like this:

And a, for ex, location-create-single.v1.yaml path definition is shown on picture below. Mention, that all $ref referes to components.v1.yaml files.

Declination

That is a VERY nice looking IDE file browser! What IDE and theme is that? – Heracles

Can you please explain in more detail why you can't use swagger-cli to merge an entire tree of files? All of your files link to each other, starting with the topmost blueprint.v1.yaml through the <component>-*.yaml files (e.g. location-*.yaml) down to the every components.v1.yaml file. What's the problem to traverse through them? – Nonflammable

Does this answer your question? How do I combine multiple OpenAPI 3 specification files together? – Nonflammable

Answer 1

I don't think there is a "native" OpenAPI solution to your problem. People are discussing for a while about OpenAPI overlays/extends/merges. There is currently (2020-04-24) not any consensus about this topic.

Although you could implement your own tool or use an existing one to preprocess your blueprint.v1.yaml and generate a "merged OAS".

Flosser

P. Savrov any feedback about this answer ? – Flosser

Answer 2

openapi-generator-cli tool is able to merge specification files into single one using the openapi-yaml generator:

openapi-generator-cli generate -i blueprint.v1.yaml -g openapi-yaml

where -i option specifies an input OpenAPI document.

Nonflammable

Could you explain which option allows you to merge specification files into a single one? It seems to only reference 1 file, rather than multiple or a directory to merge. – Rawboned

@Rawboned the command above dereferences all the $refs in the specified yaml. With the $ref keyword you can reference other documents in any directory you want. The final spec will include all the referenced content. – Nonflammable

Answer 3

go-swagger has a mixin command that merges paths, definitions, etc. from multiple OpenAPI specifications, skipping duplicate definitions as required.

Gymnosperm

Seems to be only for Swagger 2.0 (Not OpenAPI v3) – Prosecutor