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, *, category: Literal['Archive', 'Batch download', 'Metadata', 'Request archival', 'Miscellaneous', 'test', 'External IDentifiers', 'Provenance'], noargs: bool = False, tags: List[str] = [], 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

  • 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

    • deprecated: display the entry point as deprecated in the index

  • 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]#