Project

General

Profile

Feature #24763

mgr/dashboard: Automatic generation of REST API documentation based on Python docstrings

Added by Ricardo Dias 8 months ago. Updated 8 days ago.

Status:
Need Review
Priority:
Normal
Assignee:
Category:
dashboard/general
Target version:
Start date:
07/04/2018
Due date:
% Done:

0%

Source:
Tags:
dashboard, swagger, openAPI, python
Backport:
Reviewed:
Affected Versions:
Pull request ID:

Description

In the current implementation of the Ceph-Dashboard we already generate a Swagger-UI page with the available REST API endpoints that are implemented in the dashboard backend. This generation is automatic and it's done when the dashboard module starts.

The REST API endpoints correspond to Python class methods decorated with `@Endpoint`, and, in the special case of the REST controllers, correspond to the following class methods: `list`, `create`, `get`, `set`, `delete`, `bulk_set`, `bulk_delete`.

The objective of this feature is to parse the docstrings of the endpoint methods and add these to the Swagger-UI page to document each endpoint.
We could also agree on a particular python docstring format to allow the specification of the parameters types and return types and add also add that information to the Swagger-UI page.

History

#1 Updated by Lenz Grimmer 8 months ago

  • Assignee deleted (Lenz Grimmer)

#2 Updated by Lenz Grimmer 3 months ago

  • Assignee set to Tina Kallio
  • Target version set to v14.0.0

#3 Updated by Tina Kallio 2 months ago

There is no suitable off-the-shelf parser that can be used to accomplish this.

Another way to obtain information for the documentation directly from the code is to use annotations and decorators. This approach will be used instead.

However, function annotations can not be used since it is not compatible with Python2.

It is desirable but not mandatory that the solution includes responses.

#5 Updated by Lenz Grimmer 20 days ago

  • Pull request ID set to 26227

#6 Updated by Lenz Grimmer 20 days ago

  • Status changed from New to Need Review

#7 Updated by Lenz Grimmer 8 days ago

  • Subject changed from dashboard: Automatic generation of REST API documentation based on Python docstrings to mgr/dashboard: Automatic generation of REST API documentation based on Python docstrings

Also available in: Atom PDF