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.