Use-case: A way of adding documentation to generated (API) definitions

[ponelat]

This is to explore the use case of separating the machine generated API definition (via annotated code, traffic inference, etc) and the human-facing documentation (summary, description, etc). For context, we're thinking of OpenAPI definitions but this could apply to others (ie: AsyncAPI, etc).

There are cases when documentation writers need to dive into codebases to make these changes and Overlays can help alleviate that need.
It's also possible to create different documentation for different audiences (cough maybe even i11n/multi-lingual support).

The use case appears straightforward. Take a base document and an overlay document to produce a final document.

What appears to be more interesting is adding append/prepend actions as ways of extending strings, specifically description (thanks @hkosova for the idea)!

[ponelat]

This talk has a good example of some workflows by documentation writers: https://passo.uno/posts/how-to-assist-api-design-as-a-technical-writer/

[ponelat]

Documentation authors are also often in the position of adding more than just description, summary, etc. Since developers can be lazy and forget to document more structural things, like missing response codes, missing formats, etc.
Use case:
As documentation authors, we often need to update definitions after they've been generated but before they've been released to their audience, ie: at any time. There is a need to amend definitions at all times (ie: not waiting for the machine generated ones).

Another possible use-case is to report on these changes to the developer and then again to the documentor.
Report to the developer what should be described in the source of truth (ie: the missing response code)
Report to the documentor what is now redundant (ie: it has now been described in the base definition)

• Base definition
• Documentor adds a 401 response via Overlays.
• <some-tool> generate a report for developers, "Hey you missed describing a 401 response, please add to code".
• <some-tool> can flag the documentor, that the 401 in the overlay is redundant (ie: the base definition already has this).
• Documentor removes the 401 response from the Overlay

[ponelat]

Existing/Prior work for this use-case

• feat: enable built-in decorators redocly-demo/decorators-demo#1 (thanks @adamaltman)!

[ponelat]

Added an example of a code-first generated OpenAPI definition and a small Overlay file that patches/fixes it.
https://gist.github.com/ponelat/9de63f103c502f48066085941118037e (includes a README with details)

[lornajane]

This was a useful discussion, but it's a bit outdated so I'm closing it