Add api-generation support w/ swagger-ui-tag

pedro-psb commented 3 months ago

This adds rest-api generation to the docs.

It uses the swagger-ui-tag plugin
It fetches the api.json from one of the two urls (whichever is available):
- https://docs.pulpproject.org/{repo_name}/api.json
- https://docs.pulpproject.org/{repo_name}/_static/api.json
It relies that we'll keep publishing the api.json as we currently do (which is a fact I was missing).

Observations (about rest api gen):

Performance: The plugin adds about 27s of overhead, but I could find a way to optmize it up to 2s by filtering the filenames the plugin tries to process: https://github.com/blueswen/mkdocs-swagger-ui-tag/pull/26
No anchors: Because swagger-ui is js-generated, we don't get anchors out of the box. We'd need a javascript wizard to send a patch on that. Do we know one?
Grouping: We may be able to add better grouping using a swagger-ui plugin. This video shows how on a slightly different context. Something to think for the future.

Preview

closes: #40

pedro-psb commented 3 months ago

Converted to draft because I want to wait the performance issue to be resolved.

pedro-psb commented 2 months ago