Generate static documentation of REST API based on existing OpenAPI specification

[uguy]

Bonita OpenAPI specification lives in this repository https://github.com/bonitasoft/bonita-openapi.
But a kind of duplicate lives in bonita-doc repository as static asciidoc file (https://github.com/bonitasoft/bonita-doc/blob/2022.2/modules/api/pages/rest-api-overview.adoc).

This situation can lead to a desynchronization between the two API documentations 😟 .

Developer often ask for an OpenAPI spec of Bonita REST APIs. (Some might want to generate client code from spec, so yaml format exposure is required).

Every other want to browse/search documentation for their implementations (required to be SSO friendly).

Important: OpenAPI specification has its own lifecycle (not bound to Bonita versions). This means that the same documentation is used for many Bonita versions ( = many documentation versions)

Two options:

• Generate AsciiDoc sources to be processed as any other Antora page in bonita-doc repository (one page per Bonita versions but not ideal) (PoC in this PR feat(rest-api): static api doc bonita-doc#2181)
• Generate a separated site hosting API documentation and point to it from Bonita documentation (using classic Redoc customization)

Useful links:

• https://redocly.github.io/redoc/
• https://openapi-generator.tech/docs/generators/asciidoc
• antora-collector-extension
  • https://gitlab.com/antora/antora-collector-extension
  • usage example in Antora zulip chat

Formerly requested with #39

[uguy]

Links about generator based on OpenAPI specs :

• https://openapi-generator.tech/docs/generators/#documentation-generators
• https://openapi.tools/#documentation

[uguy]

Generated static html page with Redoc hosted here as a sample : https://bonita-api-doc.netlify.app/
The trouble is that the static generator don't handle markdown description whereas Redoc Reactjs component does (but not SEO friendly)

More control is available from https://redocly.com/docs/api-reference-docs/guides/on-premise-cli-build/ but only for enterprise plan 😬

[uguy]

Spec versioning (hence multiple doc version hosting) should be supported. For now, there were no API break but this will come in future Bonita releases.

[uguy]

An interesting option seems to be hosting Redoc pages in a dedicated site referenced by main Bonita documentation.
We would need to :

• generated static page per spec version (with redoc-cli)
• host different version of the spec (generated doc)
• offer a way to the user to change/target doc version
• add analytics to follow usage
• generate a local dev preview, publish a preview on PR push
• automated publication of new tag (tagged content may contain the html doc to be hosted)
• Filter old tag because "out of support"
• handle default route : / , /latest , /x.x.x => latest tagged doc - /y.y.y => y.y.y spec doc version

and also :

• Be clear on compatibility matrix between OpenAPI spec version and bonita versions !

[uguy]

Question remains, do we orchestrate deployment from a separate repository and keep all html/site stuff there and only the spec in bonta-openapi repository ? Or do we try to merge and handle all this stuff from the existing repository (keeping close editing and rendering)

[uguy]

PoC in progress in OpenAPI spec repository bonitasoft/bonita-openapi#60

[benjaminParisel]

This issue is closed with the work around this subject. We created a repository https://github.com/bonitasoft/bonita-rest-documentation-site and the production site is available here

I will close this issue. If some issue is found, please open it on dedicated GitHub repository