edx_api_doc_tools module

Tools for writing and generating API documentation for Open edX REST APIs.

In this file is the public Python API for REST documentation.

class edx_api_doc_tools.ApiSchemaGenerator(info, version='', url=None, patterns=None, urlconf=None)

A schema generator for /api/*.

Only includes endpoints in the /api/* url tree, and sets the path prefix appropriately.

determine_path_prefix(paths)

Return common prefix for all paths.

get_endpoints(request)

Return dict of endpoints to be displayed.

class edx_api_doc_tools.ParameterLocation

Location of API parameter in request.

edx_api_doc_tools.exclude_schema(view_func)

Decorate an API-endpoint-handling function to exclude it from the API docs.

Example:

class MyView(APIView):

    @schema(...)
    def get(...):
        pass

    @exclude_schema
    def post(...):
        pass
edx_api_doc_tools.exclude_schema_for(*method_names)

Decorate a class to exlcude one or more of of its methods from the API docs.

Parameters

method_names (list[str]) – Names of view methods whose operations will be excluded from the generated API documentation.

Example:

@schema_for('get', ...)
@schema_for('delete', ...)
@exclude_schema_for('put', 'patch')
class MyView(RetrieveUpdateDestroyAPIView):
    pass
edx_api_doc_tools.exclude_schema_for_all(view_class)

Decorate a class to exlcude all of its methods from the API docs.

Parameters

view_class (type) – A type, typically a subclass of View or ViewSet.

Example:

@exclude_schema_for_all
class MyView(RetrieveUpdateDestroyAPIView):
    pass
edx_api_doc_tools.get_docs_cache_timeout()

Return OPENAPI_CACHE_TIMEOUT setting, or zero if it’s not defined.

edx_api_doc_tools.get_docs_urls(docs_data_view, docs_ui_view)

Get some reasonable URL patterns to browsable API docs and API docs data.

If these URL patterns don’t work for your service, feel free to construct your own.

Parameters
  • docs_data_view (openapi.Info) – JSON/YAML view for API docs data.

  • docs_ui_view (openapi.Info) – Nice HTML view for API docs.

Returns: list[RegexURLPattern]

A list of url patterns to the API docs.

Example:

# File: urls.py
from edx_api_doc_tools import get_docs_urls
from .views import custom_doc_data_view, custom_doc_ui_view
urlpatterns = [ ... ] # Your URL patterns.
urlpatterns += get_docs_urls(custom_doc_data_view, custom_doc_ui_view)
edx_api_doc_tools.is_schema_request(request)

Return whether this request is serving an OpenAPI schema.

edx_api_doc_tools.make_api_info(title='Open edX APIs', version='v1', email='oscm@edx.org', description='APIs for access to Open edX information')

Build an API info object.

Parameters
  • title (str) – The title of the API.

  • version (str) – The version of the API.

  • email (str) – Contact email address for API support or questions.

  • description (str) – Description of the API.

Returns: openapi.Info

edx_api_doc_tools.make_docs_data_view(api_info, api_url_patterns=None)

Build View for API documentation data (either JSON or YAML).

Parameters
  • api_info (openapi.Info) – Information about the API.

  • api_url_patterns (list of url patterns) – URL patterns that API docs will be generated for

Returns: View

Example:

from edx_api_doc_tools import make_api_info, make_docs_data_view
api_info = make_api_info(title="Awesome API", version="v42")
my_data_view = make_docs_data_view(api_info)
edx_api_doc_tools.make_docs_ui_view(api_info, api_url_patterns=None)

Build View for browsable API documentation.

Parameters
  • api_info (openapi.Info) – Information about the API.

  • api_url_patterns (list of url patterns) – URL patterns that API docs will be generated for

Returns: View

Example:

from edx_api_doc_tools import make_api_info, make_docs_ui_view
api_info = make_api_info(title="Awesome API", version="v42")
my_ui_view = make_docs_ui_view(api_info)
edx_api_doc_tools.make_docs_urls(api_info, api_url_patterns=None)

Create API doc views given an API info object.

Parameters
  • api_info (openapi.Info) – Information about the API.

  • api_url_patterns (list of url patterns) – URL patterns that API docs will be generated for

Returns: list[RegexURLPattern]

A list of url patterns to the API docs.

Example:

# File: urls.py
from edx_api_doc_tools import make_docs_urls, make_api_info
urlpatterns = [ ... ] # Your URL patterns.
api_info = make_api_info(title="Awesome API", version="v42")
urlpatterns += make_docs_urls(api_info)
edx_api_doc_tools.parameter(name, in_, param_type, description=None)

Define a typed parameter.

Parameters
  • name (str) – The name of the parameter.

  • in (ParameterLocation attribute) – How the parameter is passed in.

  • param_type (type|str) – a member of PARAM_TYPES.

  • description (str) – Description of the parameter.

Returns: openapi.Parameter

edx_api_doc_tools.path_parameter(name, param_type, description=None)

Define a parameter in the endpoint’s path.

Type must still be specified.

edx_api_doc_tools.query_parameter(name, param_type, description=None)

Define a parameter in the endpoint’s querystring.

Type must still be specified.

edx_api_doc_tools.schema(body=None, parameters=None, responses=None, summary=None, description=None)

Decorate an API-endpoint-handling function to specify its schema.

The operation summary and description are taken from the function docstring. All description fields should be in Markdown and will be automatically dedented.

Parameters
  • body – Optional payload used for POST, PUT, and PATCH requests. Accepts a serializer class.

  • parameters (list[openapi.Parameter]) – Optional list of parameters to the API endpoint.

  • responses (dict[int, object]) – Optional map from HTTP statuses to either: * a serializer class corresponding to that status * a string describing when that status occurs * an openapi.Schema object * None, which indicates “don’t include this response”.

  • summary (str) – One-line summary of operation. If None, we attempt to extract it from the first line of the docstring.

  • description (str) – Optional multi-line description of operation. If None, we attempt to extract it from the rest of the docstring.

  • request_body (Serializer) – Optional serializer class corresponding to the body of the request.

edx_api_doc_tools.schema_for(method_name, docstring=None, **schema_kwargs)

Decorate a class to specify a schema for one of its methods.

Useful when the method you are describing is not defined inside of your class body, but is instead defined somewhere up in the DRF view hierarchy. (For applying a schema directly to a method, use the schema() decorator).

DRF method names include: list, retrieve, get, post, create, put, update, patch, partial_update, delete, and destroy.

Parameters
  • method_name (str) – Name of the method to decorate.

  • docstring (str) – Optional summary and description of the operation, which takes the same format that schema() expects of function docstrings (that is, a summary line, followed by a newline, followed by one or more lines of description).

  • **schema_kwargs – kwargs to pass to schema().

edx_api_doc_tools.string_parameter(name, in_, description=None)

Define a string parameter.

Location must still be specified.