swh.web.api.apidoc module

exception swh.web.api.apidoc.APIDocException

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'], noargs: bool = False, tags: List[str] = [], api_version: str = '1')

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)

Build documentation data for the decorated api endpoint function

swh.web.api.apidoc.format_docstring(**substitutions)