Pitch

Summary

There should be a place, unrelated to a running OpenBAS instance, to expose a nice Swagger UI with the correct version of the API spec (relative to the version selector on the docs page header).

Business benefit

• Community engagement: easy way to point to specific bits of API specs and for community members to explore the API for possible devs
• Docs completeness: there is a need from other places in the greater Filigran documentation corpus to refer to the API specs; e.g. from the PyOBAS docs

Limits and no go

• Swagger UI should be static and embedded in the docs repository bundle. It should not be dependent on a running OpenBAS server.
• The default Swagger UI theme is what it is and does not conform to the rest of the docs website theme. No effort proposed to improve this.
• Care from individual developers should be given to keep the static API specs file in sync with the version selector (i.e. latest patch-version Z in a given X.Y.Z version) whenever there is a release (addition to release process).

Example PoC

cc @jborozco @EllynBsc @RomuDeuxfois @Dimfacion @guillaumejparis