Generate API protocols based on tags

[olejnjak]

Currently OpenAPI generator generates a single APIProtocol for all client calls.

It would be a good improvement if it would be possible to generate a protocol based on tags in the spec. So given the following spec, two protocols would be generated PetsAPIProtocol & StoreAPIProtocol.

paths:
  /pet/findByStatus:
    get:
      summary: Finds pets by Status
      tags:
        - pets
      ...
  /pet:
    post:
      summary: Adds a new pet to the store
      tags:
        - pets
      ...
  /store/inventory:
    get:
      summary: Returns pet inventories
      tags:
        - store
      ...

Based on https://x.com/czechboy0/status/1703869135682195838?s=20

[czechboy0]

I think that's a good idea. Would help with large documents, and even when implementing servers, it could help break up the API handler a bit.

This should be doable even in a backwards compatible way, as we could continue to generate

protocol APIProtocol: PetsAPIProtocol, StoreAPIProtocol {} so those who still want to just use a single object for everything could continue to do so.

Still, this should go through a proposal, but should be considered before 1.0 in case we choose to do it in an API-breaking way.

If anyone wants to take it on and go through the proposal and implementation process, that'd be great. We can help guide you through the process.

[olejnjak]

Proposal in #287

[simonjbeaumont]

@olejnjak Thanks for taking the time to file this and to write up the proposal!

As it happens, we've been considering adding support for pruning the OpenAPI document to just the things a user wants to use. We were considering a more expressive approach that extends beyond the OpenAPI tags. For example, you could ask to generate:

• A list of operations by operation ID, (path, method) pair, or tag.
• (Maybe) A list of schemas by name.

The feature would then prune the OpenAPI document before generation to only include these items and the transitive closure of all those items dependencies. Generation would then proceed as it does today, on this subset.

The missing part from the proposal above is that we would not make changes to the generated namespaces—we would still have APIProtocol.

Would this fit your use case?

[czechboy0]

Just to add to Si, you could then generate all the operations for one tag into one module, making the fully qualified protocol name ModuleA.APIProtocol, other tag into another module (ModuleB.APIProtocol), etc, allowing splitting a large doc into several smaller parts.

[simonjbeaumont]

@olejnjak Just a heads up that SOAR-0008 proposal is up in #303, which might go some way to meet your requirements.