swh.web.api.apidoc module

exception swh.web.api.apidoc.APIDocException[source]

Bases: Exception

Custom exception to signal errors in the use of the APIDoc decorators

swh.web.api.apidoc.api_doc(route: str, noargs: bool = False, need_params: bool = False, tags: List[str] = [], handle_response: bool = False, api_version: str = '1')[source]

Decorator for an API endpoint implementation used to generate a dedicated view displaying its HTML documentation.

The documentation will be generated from the endpoint docstring based on sphinxcontrib-httpdomain format.

Parameters
  • route – documentation page’s route

  • noargs – set to True if the route has no arguments, and its result should be displayed anytime its documentation is requested. Default to False

  • need_params – specify the route requires query parameters otherwise errors will occur. It enables to avoid displaying the invalid response in its HTML documentation. Default to False.

  • tags

    Further information on api endpoints. Two values are possibly expected:

    • hidden: remove the entry points from the listing

    • upcoming: display the entry point but it is not followable

  • handle_response – indicate if the decorated function takes care of creating the HTTP response or delegates that task to the apiresponse module

  • api_version – api version string

swh.web.api.apidoc.get_doc_data(f, route, noargs)[source]

Build documentation data for the decorated api endpoint function

swh.web.api.apidoc.format_docstring(**substitutions)[source]