Tools for writing and generating API documentation for Open edX REST APIs.
In this file is the public Python API for REST documentation.
A schema generator for /api/*
.
Only includes endpoints in the /api/*
url tree, and sets the path prefix
appropriately.
Return common prefix for all paths.
Return dict of endpoints to be displayed.
Location of API parameter in request.
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
Decorate a class to exlcude one or more of of its methods from the API docs.
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
Decorate a class to exlcude all of its methods from the API docs.
view_class (type) – A type, typically a subclass of View or ViewSet.
Example:
@exclude_schema_for_all
class MyView(RetrieveUpdateDestroyAPIView):
pass
Return OPENAPI_CACHE_TIMEOUT setting, or zero if it’s not defined.
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.
docs_data_view (openapi.Info) – JSON/YAML view for API docs data.
docs_ui_view (openapi.Info) – Nice HTML view for API docs.
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)
Return whether this request is serving an OpenAPI schema.
Build an API info object.
Returns: openapi.Info
Build View for API documentation data (either JSON or YAML).
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)
Build View for browsable API documentation.
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)
Create API doc views given an API info object.
api_info (openapi.Info) – Information about the API.
api_url_patterns (list of url patterns) – URL patterns that API docs will be generated for
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)
Define a typed parameter.
Returns: openapi.Parameter
Define a parameter in the endpoint’s path.
Type must still be specified.
Define a parameter in the endpoint’s querystring.
Type must still be specified.
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.
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.
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
.
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()
.
Define a string parameter.
Location must still be specified.