Project

General

Profile

Documentation #45863

Feature #40907: mgr/dashboard: REST API improvements

mgr/dashboard: generate and publish REST API document for backend

Added by Kiefer Chang 8 months ago. Updated 3 months ago.

Status:
Resolved
Priority:
Normal
Category:
dashboard/documentation
Target version:
% Done:

100%

Tags:
Backport:
Reviewed:
Affected Versions:
Pull request ID:

Description

We can generate Swagger API document for the Dashboard backend:
- Nightly: to ensure nothing is broken.
- When there is a new major or minor version released.

And publish it for reference, some ideas:
- To SwaggerHub.
- Any site can host static contents: github.io, Ceph site,..etc.

History

#1 Updated by Kiefer Chang 8 months ago

  • Parent task set to #40907
  • Pull request ID deleted (40907)

#2 Updated by Courtney Caldwell 7 months ago

  • Status changed from New to In Progress
  • Assignee set to Courtney Caldwell

Looking at SwaggerHub as publishing method or ReadTheDocs.

#3 Updated by Lenz Grimmer 7 months ago

Courtney Caldwell wrote:

Looking at SwaggerHub as publishing method or ReadTheDocs.

We could do both, just to make sure we have broader coverage. The thing that concerns me a bit is that we'd be adding yet another dependency on some third party service that actually would like us to pay money for this and may retract their free tier at any time.

Note that the Ceph documentation is already on RTD: https://ceph.readthedocs.io/ - how about publishing it via https://ceph.readthedocs.io/api/ there?

#4 Updated by Courtney Caldwell 7 months ago

The RTD method does look like the best idea; however, it seems most projects to link sphinx (our current generation method) and swagger/OpenAPI are older than the v3.0 specification of OpenAPI; I'm going to try importing a package that seems to be simple enough to implement that takes the input YAML/JSON from Swagger and builds out a Sphinx-doc.

If anyone knows of a modern python module that interfaces Swagger's output (which is what we currently use for API documentation) to Sphinx (modern being more recent than late 2017, or specifically referencing OpenAPI 3.0), feel free to share.

https://sphinxcontrib-openapi.readthedocs.io/ is what I'm testing now.

Also, worth noting is we send the docs directly to a CherryPy server, rather than generating the json file seperately (as noted in mgr/dashboard/modules/docs.py); it's passed as a large HTML string to the CherryPy serverlet.

This is efficient as far as avoiding some overhead, but inadequate for static generation: perhaps generating the json file during a build would be better, and having cherrypy call on it. -- looking into possible work-arounds since we need a static json to generate the sphinx-based documentation.

#5 Updated by Ernesto Puerta 7 months ago

  • Pull request ID set to 36016

#6 Updated by Ernesto Puerta 7 months ago

  • Status changed from In Progress to Fix Under Review

#7 Updated by Lenz Grimmer 4 months ago

  • Status changed from Fix Under Review to Resolved
  • Target version set to v16.0.0

#8 Updated by Alfonso Martínez 3 months ago

  • % Done changed from 0 to 100

Also available in: Atom PDF