OpenAPI spec and documentation transclusion

[catkins-miso]

We want to keep the prose used in the API specification and the external documentation DRY. We may eventually have need to include additional contributor information and/or server locations both for interactive testing and links to external documentation, while the source of truth for those values would be external.

Goals:

• Should be able to include the content in both the OpenAPI spec and the gh-pages site associated with this repo.
• Should be able to edit the content in VS Code and preview locally
• Should be able to build and release the OpenAPI spec via GH Actions
• The same branch should be the source of the spec itself, the Redoc site, and the gh-pages.

Some relevant constraints:

GH Pages can be built from a subfolder on a branch

The source branch can be any branch in your repository, and the source folder can either be the root of the repository (/) on the source branch or a /docs folder on the source branch. Whenever changes are pushed to the source branch, the changes in the source folder will be published to your GitHub Pages site.

GH Wiki doesn't support transclusion

Jekyll supports data files

This could be used, for example, to pull docs/_data/spec_description.yaml into the the gh-pages via standard Jekyll features, then using e.g. yq (.info.description)=$(yq .description docs/_data/spec_description.yaml) to include it in the openapi.yaml

There is a yq gh Action

This would be an effective way to ensure that every commit builds the OpenAPI spec as well as the gh-pages. One problem with using this is that we want to the same transclusion to happen locally. How might we reuse the yq commands?

The redoc visualization can be included via HTML tags and Jekyll supports raw HTML

VS Code supports .devcontainers and there is a run on save extensions

Proposal

• Setup development branch to use .devcontainer and include
  • yq
  • mega-linter?
  • install 42crunch vs code extension
• Write a script that is invoked when the container starts and on save of any files is docs/_data or openapi-dev.yaml
  • The script will generate openapi.yaml which will be in .gitignore
  • The script will be invoked by gh action as well
  • openapi.yaml will be used as it is today, i.e., for the Redoc site and as the primary deliverable
• Create a Jekyll page for the Redoc spec visualization
• Another to include the ADRs, the ADRs can be included as docs/_data/adrs.yaml
• The devcontainer and the GH action(s) use the same Dockerfile via entrypoint.sh
• setup precommit hook for the above, too

[caindy]

Another option that I'm exploring is using redocly split and redocly bundle. The former would happen once as part of a check-in to decompose the openapi.yaml into smaller files. The latter would be used at build time to generate the single-file docs/openapi.yaml again.

I think the folder structure would be

docs/_data
    |___/components
    |   |_____/headers
    |   |_____/parameters
    |   |_____/responses
    |   |_____/schemas
    |___/paths
|___/openapi.yaml <-- build output, should be in .gitignore

This setup will likely require a custom workflow to generate the GH Pages