Known use cases for Overlays

[ponelat]

As we shape Overlays, it'll be most helpful to target specific use cases that prompted this specification in the first place.

[ponelat]

A quick first pass at OpenAPI issues that might be helped with Overlays and a crude categorization of them...

Categories

• I18n / Multilingual support for OpenAPI
• Traits/Groups of re-usable components (eg: parameters/responses).
• Envelopes/placeholders (ie: pagination)
• Context specific API definitions (ie: one API definition, different views for different audiences)

Issues

• https://github.com/OAI/OpenAPI-Specification/issues/2281
• https://github.com/OAI/OpenAPI-Specification/issues/1843
• https://github.com/OAI/OpenAPI-Specification/issues/1722
• https://github.com/OAI/OpenAPI-Specification/issues/1442
• Is it possible to group parameters ? OpenAPI-Specification#1364
• https://github.com/OAI/OpenAPI-Specification/issues/445
• https://github.com/OAI/OpenAPI-Specification/issues/613
• DRY up the PATCH <- POST <- GET inheritance chain OpenAPI-Specification#2201
• Vary presence and requirement of properties with CRUD operation OpenAPI-Specification#1497
• Aliasing query parameters OpenAPI-Specification#2298
• [Question] Extend/override properties of a parameter  OpenAPI-Specification#2026
• Create vs update, PUT / POST / PATCH, and minimal OpenAPI redundancy OpenAPI-Specification#1453
• https://github.com/OAI/OpenAPI-Specification/issues/1853
• Is there a way to make the $ref even more reusable with placeholders? OpenAPI-Specification#1749
• Common response/payload object but different data defined per API? OpenAPI-Specification#773
• Message format 'wrappers' OpenAPI-Specification#555
• Multilingual support OpenAPI-Specification#1740
• Question: How to define reusable headers that can be used in both request and response OpenAPI-Specification#1574
• Proposal - extract Swagger Examples into separate files of mappings. OpenAPI-Specification#1533
• https://github.com/OAI/OpenAPI-Specification/issues/1339
• Vary presence and requirement of properties with CRUD operation OpenAPI-Specification#1497
• DRY Specifications via $ref OpenAPI-Specification#1462
• Extracting common properties OpenAPI-Specification#756
• Visibility and display attributes OpenAPI-Specification#569
• Add default responses OpenAPI-Specification#563
• [Meta issue] Structural improvements OpenAPI-Specification#560
• Ability to define generic wrapper around the output OpenAPI-Specification#519
• Mark endpoints as private/hidden OpenAPI-Specification#433
• Support for multiple $refs inside a single object OpenAPI-Specification#417
• Definitions for error responses OpenAPI-Specification#398
• Share header with multiple response objects OpenAPI-Specification#369
• Overloading OpenAPI-Specification#298
• Allow for overloading/aliasing of route path OpenAPI-Specification#213

[earth2marsh]

Copying my comments from the Feb 15, 2022 discussion:

Another use case worth noting is how middleware might transform an API surface. For example, the moment you proxy an API, you've changed the server. You might change the auth model, say from mtls to OAuth. There are many changes like this I can imagine, but I think that this kind of transformation is worth adding as a use case.

Another is to add additional metadata for codegen or test generation. An overlay might help to keep those separate. Continuing on that line of thought... examples can really blow up the size of an OpenAPI document. Why not maintain examples separately and mix them in with an overlay (which brings up the question of what approaches would feel relatively more natural for authors).

One last thought... from an end user perspective it is best to have a flattened version of a multi-part document (for example, no load failure from unavailable resource or permission prob). If we can make that assumption, it may help simplify how we think about the authoring process.

[kevinswiber]

With respect to the envelope/placeholder use case, there are some options with JSON Schema alone. See here: #20 (comment)

[kscheirer]

• Multilingual support OpenAPI-Specification#1740, added example solutions there, overlay seems good
• Add default responses OpenAPI-Specification#563, added example solutions there, overlay seems good
• Mark endpoints as private/hidden OpenAPI-Specification#433, added example solution there, overlay seems good

[kscheirer]

• Question: How to define reusable headers that can be used in both request and response OpenAPI-Specification#1574, added example solution, overlay works, but using component.headers in both request parameter and response header is awkward
• https://github.com/OAI/OpenAPI-Specification/issues/1339, added example solution, overlay seems good

[kscheirer]

• Visibility and display attributes OpenAPI-Specification#569, visibility same as Mark endpoints as private/hidden OpenAPI-Specification#433, overlay does not help with ordering of operations within spec
• https://github.com/OAI/OpenAPI-Specification/issues/1853, overlay + traits seem good, no examples needed

[kscheirer]

• https://github.com/OAI/OpenAPI-Specification/issues/445, added example solutions, overlay seems good
• Is it possible to group parameters ? OpenAPI-Specification#1364, comment and link to #445

I'm just going to update this comment to keep track of which ones I've responded on. I jumped around and picked from all over to start with.

Overlays could be helpful (10/33):

• https://github.com/OAI/OpenAPI-Specification/issues/2281
• https://github.com/OAI/OpenAPI-Specification/issues/1843
• https://github.com/OAI/OpenAPI-Specification/issues/1722
• https://github.com/OAI/OpenAPI-Specification/issues/1442
• Is it possible to group parameters ? OpenAPI-Specification#1364
• https://github.com/OAI/OpenAPI-Specification/issues/445
• https://github.com/OAI/OpenAPI-Specification/issues/613
• DRY up the PATCH <- POST <- GET inheritance chain OpenAPI-Specification#2201
• Vary presence and requirement of properties with CRUD operation OpenAPI-Specification#1497
• [Question] Extend/override properties of a parameter  OpenAPI-Specification#2026
• https://github.com/OAI/OpenAPI-Specification/issues/1853
• Multilingual support OpenAPI-Specification#1740
• Question: How to define reusable headers that can be used in both request and response OpenAPI-Specification#1574
• https://github.com/OAI/OpenAPI-Specification/issues/1339
• Vary presence and requirement of properties with CRUD operation OpenAPI-Specification#1497
• DRY Specifications via $ref OpenAPI-Specification#1462
• Extracting common properties OpenAPI-Specification#756
• Visibility and display attributes OpenAPI-Specification#569
• Add default responses OpenAPI-Specification#563
• [Meta issue] Structural improvements OpenAPI-Specification#560
• Ability to define generic wrapper around the output OpenAPI-Specification#519
• Mark endpoints as private/hidden OpenAPI-Specification#433
• Support for multiple $refs inside a single object OpenAPI-Specification#417
• Definitions for error responses OpenAPI-Specification#398
• Share header with multiple response objects OpenAPI-Specification#369
• Overloading OpenAPI-Specification#298
• Allow for overloading/aliasing of route path OpenAPI-Specification#213

Overlays do not look helpful (6/33):

• Is there a way to make the $ref even more reusable with placeholders? OpenAPI-Specification#1749
• Create vs update, PUT / POST / PATCH, and minimal OpenAPI redundancy OpenAPI-Specification#1453
• Proposal - extract Swagger Examples into separate files of mappings. OpenAPI-Specification#1533
• Aliasing query parameters OpenAPI-Specification#2298
• Common response/payload object but different data defined per API? OpenAPI-Specification#773
• Message format 'wrappers' OpenAPI-Specification#555

[ponelat]

Thank you for the work going through the examples, @kscheirer !

[kscheirer]

thanks @ponelat, just updated a few more! sorry for the delay, my august became very busy.

[rafalkrupinski]

Just wanted to add my use cases as a client generator developer:

• 3rd party description updates:

  I'm working with a OpenAPI description that doesn't 100% represent its service. E.g. some properties are missing nullable attribute making the responses not validate against the schema. In result I have a JSONPatch files to fix various parts of the service's openapi description.

• Enhancements for programming languages

  • Some OAS elements could be translated to language-level constructs, like enums. Problem is, enum in OAS is a list and in programming languages it's typically a kind of a mapping (name := value). So I also have JSON files that add names (x-...) to enum values.
  • Similar case for names: keys in JSON allow much broader set of characters than some programming languages. Character escaping leads to ugly names. So I have another x- attribute to provide friendly aliases.

[lornajane]

Some good use cases from @philsturgeon in comment #45 (reply in thread)

[mikeschinkel]

Here is a discussion post about three (3) of the use-cases I have needed to support codegen:

1. Rename a schema and change one of the properties of the renamed schema
2. Delete selected schema properties
3. Subset the OpenAPI doc based on a criteria, in my case the values of the endpoints

[philsturgeon]

I've just used Overlays to add Microcks-specific mocking examples to an OpenAPI which would otherwise look a bit weird with them in due to templating syntax showing up in documentation.

https://github.com/bump-sh-examples/train-travel-api/blob/main/.microcks/overlays.yaml