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.

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