Create a decorator that supports structured overlays

[lornajane]

Is your feature request related to a problem? Please describe.

Users often want to override summary and description fields in their OpenAPI specifications.

Describe the solution you'd like

There's an initiative in the OpenAPI project called Overlays. We can use the same format and allow a user to supply a [structured overlay consisting of a single action object] that shadows the user's existing OpenAPI structure and replaces fields as needed. This is a partial implementation of the proposed overlays standard, but one that is most clear to understand for users, and which serves the common use case of overwriting many fields in an API description.

We can implement this as a custom plugin in the first instance. We may also need to add some validation logic for the data format.

Describe alternatives you've considered

We already offer the operation-description-override decorator so that individual operations can have their descriptions overwritten by specified markdown files but this requires a lot of entries and many extra files.

Additional context

The OpenAPI Overlays Specification is currently inactive, but it was a good idea, and adopting it is a good starting point for our feature.

[jeremyfiel]

The OpenAPI Overlays Specification is currently inactiveACTIVE, but it was a good idea, and adopting it is a good starting point for our feature.