`openapiv3`: Merge output files

[aidandj]

🚀 Feature

Merge the output files into one spec.

Supported by allow_merge and merge_file_name options in v2.

Please add a 👍 if this feature is useful/required for you.

[johanbrandhorst]

The way this worked in v2 is something I never particularly liked - the general rule of protobuf plugins is that there is one output file for one input file. The use of the merge options (and of course there were also 2 options) required users to set the strategy to all when using buf, as it is required to look at all input files at once. I'd like to avoid this in the openapiv3 plugin.

That said, this is obviously a feature that users want (my previous employer used few flags, but this was one), so I'm trying to think of other ways we can solve this problem. My current thinking is that we provide a post-processing binary (or, heck, a jq script?) that we can add to the docs, to help users perform this transformation. Thoughts?

[aidandj]

You are correct about protobuf and it's output, but as far as I can tell the artifact for an open API schema is a single json document. I would sort of call the generator incomplete if it didn't take the standard practice of multiple protobuf files and generate a single json schema for the API.

There are likely other ways to merge a schema, but I really like a generator to not require post processing. I loved about the custom annotations of the V2 generator.

[aidandj]

Think how it was done in the original v3 PR was pretty good. And it improved on the V2 version a little bit.

[aidandj]

Also, fwiw, the all strategy is default with remote plugins. So it's only an issue when using a locally built plug-in.

[johanbrandhorst]

To experiment with alternative solutions, I created a PR for openapiv3-merge: #6771. Please try it out on your workflows and let me know how you like it! I much prefer this because it preserves the protobuf semantics. I understand it's not as nice for the end-user as being able to do it directly in the generator, but I'd like to explore if this solution is sufficient.

[aidandj]

I don't know of a way this can be invoked with buf, do you?