Overlay scenarios

[darrelmiller]

Scenarios

[Emmanuel]
Adding a big chunk of OpenAPI (e.g. adding a path)
Adding beta methods
Adding vertical specific annotations
Is language translation a viable scenario for overlays?

[Ron]
Multiple environments (prod/test/staging)

[Jonathan]
Is our current solution too complex?

[Darrel]
Is versioning a scenario for overlays?

[Mike]
Annotating/extending OAS documents created from code or other API description formats
Removing private or sunsetted elements
Bulk document updates (i.e. where the overlay document is transient and generated from a UI/CLI)

[paraskakis]

1. Runtime or SLA-specific info:
   As an ops person I want to add gateway or other runtime configuration information, in the form of vendor extensiosn, or in the future OAS-native runtime configuration.
   But I don't want to pollute or lengthen the basic OAS document.
   Also as an API designer I don;t need to see the runtime information, so it's best placed in an overlay

2. Environment-specific data (extending on Ron's idea):
   As an ops person I want customized information for each environment that I deploy to. I also want the resulting documentation being driven by the overlaid OAS document to accurately reflect each environment.
   As an API designer I don't care to see this information as it can be deferred to deploy-time.

3. Adding to a base document or template:
   As a designer I want to reuse a basic API design and extend it without altering the base and by retaining the lineage to it.
   For example I want to produce a partner or internal or Beta API that has an additional method or even an entire resource.
   (Templating/Modularity/DRY)

4. The use case of vertical-specific or documentation additions:
   While overlays are a candidate for this use case I think it's not an elegant solution. I would prefer to see a mechanism where descriptions can be an array or better, a map.

[handrews]

@darrelmiller @lornajane another candidate for transfer to the Overlays repo?

[lornajane]

Yes but I don't think I have enough rights in both locations. @darrelmiller can you move this to Overlays with a note about why? I think this list would be a great basis for adding some more examples over in the Overlays repo.

[lornajane]

I think there's a translation/localisation use case too - making an API description available with description fields in another language.

[andrecedik]

Adding on the what @paraskakis already wrote:
We are currently thinking about using overlays to help our internal tooling. This is necessary because we need to download the OAS from our platform to "feed some automations with it". Unfortunately the vendor providing the platform adds OAI extensions and other things to the specs, which makes e.g. diffing of specs complicated. Therefore removing the attributes that have been added by the vendor is crucial for us.

[baywet]

For this one we'd need to review the initial scenarios here, and evaluate if any glaring gaps are still remaining or whether this is good to close with the capabilities the specification already has today.