13

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)project structure
  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 blueprint.v1.yaml content
  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: components.v1.yaml content

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. enter image description here

Raphael Medaer
  • 2,528
  • 12
  • 18
P. Savrov
  • 1,064
  • 4
  • 17
  • 29
  • That is a VERY nice looking IDE file browser! What IDE and theme is that? – light24bulbs Jul 31 '21 at 19:24
  • 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 `-*.yaml` files (e.g. `location-*.yaml`) down to the every `components.v1.yaml` file. What's the problem to traverse through them? – Ilya Serbis Aug 15 '23 at 10:00
  • Does this answer your question? [How do I combine multiple OpenAPI 3 specification files together?](https://stackoverflow.com/questions/54586137/how-do-i-combine-multiple-openapi-3-specification-files-together) – Ilya Serbis Aug 15 '23 at 12:15

3 Answers3

8

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

Raphael Medaer
  • 2,528
  • 12
  • 18
0

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

Richard Poole
  • 3,946
  • 23
  • 29
0

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.

Ilya Serbis
  • 21,149
  • 6
  • 87
  • 74
  • 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. – fuzzi Aug 15 '23 at 20:27