Guidelines for packaging openapi definitions to exchange between institutions

[jpraet]

At CBSS we package our openapi definitions as a zip file with this folder structure:

• belgif
  • common
  • v1
    • common-v1.yaml
  • problem
  • v1
    • problem-v1.yaml
• cbss
  • common
  • v1
    • common-v1.yaml
• openapi.yaml

This has the advantage that these are the original contracts as designed by the author, not manipulated by any tooling (e.g. flatten into a fat openapi). It also provides transparency on the types being imported.

But when we receive contracts from an API supplier, it is sometimes a fat openapi.yaml, or openapi.json, or swagger, ...

And API consumers also sometimes prefer to receive a fat openapi.yaml from us.

Could we have some guidelines around this?

[pvdbosch]

Current rule is [oas-reuse]. I'm okay with adding the organization level to this rule, the belgif-openapi artifacts are already compliant with this structure.

For code generation, there could be use cases where a client uses multiple APIs and only want the common types to be generated once. For SOAP services, we used to be able to unpack multiple WSDLs/XSDs, with the common XSDs overriding each other and multiple WSDLs. Then code could be generated for all WSDLs with a single generator execution.

Don't know if we can do the same for OpenAPI and if this impacts packaging of the root openapi.yaml?

A reason why I sometimes see common types copied manually to a single OpenAPI, is that the OpenAPI authors need to be able to produce a fat openapi and don't always use dev tools like maven.