Overlays Meeting (2024-08-27)

[lornajane]

No agenda, but a good turnout and I'll capture the main topics below

[lornajane]

Created an issue #44 to fill in the Introduction section of the spec before publishing. There are some other TBD section in the spec as well and those should be added before publication.

[lornajane]

Pull request open for this one now - it's #47

[lornajane]

There's some confusion over what an action.update actually does, so we need to update the wording there as it currently describes "Merging". If it's an object we update the property, but if it's an array we append to the array. To update an array entry, first remove it, then add it as a separate action to be its desired value.

[lornajane]

See #50 for clarification wording.

[lornajane]

To keep implementations aligned, let's collect some tests/examples of overlays and for a given OpenAPI input, the expected OpenAPI output. @lornajane has some in the https://github.com/lornajane/openapi-overlays-js project and will contribute these

[lornajane]

Overlays solves many very real problems, especially for documentarians, and there is already tooling implemented. One thing that we need to do to make this useful is to provide plenty of examples (on the learn site) of what can be done and how.

[philsturgeon]

I've got a few examples of real world stuff over here (scroll down a bit): https://docs.bump.sh/guides/openapi/augmenting-generated-openapi/

[lornajane]

We need to try to render the specification with Respec for publishing. @ralfhandl suggests that we can try the existing script from the main openapi repo and see what the output looks like as a starting point.

[ralfhandl]

See

• ReSpec build script #46

[lornajane]

Quite a few use cases were raised that require the contents of the target description as input. For example:

• openapi 2.0 allowed a default response - @mikekistler wants to use that content as a 4xx and 5xx response
• another suggestion from a past slack conversation was to remove a Test prefix from all schema names

We don't currently have anything that would support a capture/replace syntax, but inspiration may come from the callbacks syntax and some of the Arazzo functionality for referring to earlier responses or variables when making a request.

[lornajane]

Later this became

• Support semantic OpenAPI expressions for targets #128