Built-in API documentation¶
The built-in API documentation includes:
Documentation of API endpoints.
Automatically generated code samples for each of the available API client libraries.
Support for API interaction.
Installation¶
The coreapi
library is required as a dependency for the API docs. Make sure
to install the latest version. The Pygments
and Markdown
libraries
are optional but recommended.
To install the API documentation, you’ll need to include it in your project’s URLconf:
from rest_framework.documentation import include_docs_urls
urlpatterns = [
...
path('docs/', include_docs_urls(title='My API title'))
]
This will include two different views:
/docs/
- The documentation page itself./docs/schema.js
- A JavaScript resource that exposes the API schema.
Note: By default include_docs_urls
configures the underlying SchemaView
to generate public schemas. This means that views will not be instantiated with a request
instance. i.e. Inside the view self.request
will be None
.
To be compatible with this behaviour, methods (such as get_serializer
or get_serializer_class
etc.) which inspect self.request
or, particularly, self.request.user
may need to be adjusted to handle this case.
You may ensure views are given a request
instance by calling include_docs_urls
with public=False
:
from rest_framework.documentation import include_docs_urls
urlpatterns = [
...
# Generate schema with valid `request` instance:
path('docs/', include_docs_urls(title='My API title', public=False))
]
Documenting your views¶
You can document your views by including docstrings that describe each of the available actions. For example:
class UserList(generics.ListAPIView):
"""
Return a list of all the existing users.
"""
If a view supports multiple methods, you should split your documentation using method:
style delimiters.
class UserList(generics.ListCreateAPIView):
"""
get:
Return a list of all the existing users.
post:
Create a new user instance.
"""
When using viewsets, you should use the relevant action names as delimiters.
class UserViewSet(viewsets.ModelViewSet):
"""
retrieve:
Return the given user.
list:
Return a list of all the existing users.
create:
Create a new user instance.
"""
Custom actions on viewsets can also be documented in a similar way using the method names as delimiters or by attaching the documentation to action mapping methods.
class UserViewSet(viewsets.ModelViewset):
...
@action(detail=False, methods=['get', 'post'])
def some_action(self, request, *args, **kwargs):
"""
get:
A description of the get method on the custom action.
post:
A description of the post method on the custom action.
"""
@some_action.mapping.put
def put_some_action():
"""
A description of the put method on the custom action.
"""
documentation
API Reference¶
The rest_framework.documentation
module provides three helper functions to help configure the interactive API documentation, include_docs_urls
(usage shown above), get_docs_view
and get_schemajs_view
.
include_docs_urls
employsget_docs_view
andget_schemajs_view
to generate the url patterns for the documentation page and JavaScript resource that exposes the API schema respectively. They expose the following options for customisation. (get_docs_view
andget_schemajs_view
ultimately callrest_frameworks.schemas.get_schema_view()
, see the Schemas docs for more options there.)
include_docs_urls
¶
title
: DefaultNone
. May be used to provide a descriptive title for the schema definition.description
: DefaultNone
. May be used to provide a description for the schema definition.schema_url
: DefaultNone
. May be used to pass a canonical base URL for the schema.public
: DefaultTrue
. Should the schema be considered public? IfTrue
schema is generated without arequest
instance being passed to views.patterns
: DefaultNone
. A list of URLs to inspect when generating the schema. IfNone
project’s URL conf will be used.generator_class
: Defaultrest_framework.schemas.SchemaGenerator
. May be used to specify aSchemaGenerator
subclass to be passed to theSchemaView
.authentication_classes
: Defaultapi_settings.DEFAULT_AUTHENTICATION_CLASSES
. May be used to pass custom authentication classes to theSchemaView
.permission_classes
: Defaultapi_settings.DEFAULT_PERMISSION_CLASSES
May be used to pass custom permission classes to theSchemaView
.renderer_classes
: DefaultNone
. May be used to pass custom renderer classes to theSchemaView
.
get_docs_view
¶
title
: DefaultNone
. May be used to provide a descriptive title for the schema definition.description
: DefaultNone
. May be used to provide a description for the schema definition.schema_url
: DefaultNone
. May be used to pass a canonical base URL for the schema.public
: DefaultTrue
. IfTrue
schema is generated without arequest
instance being passed to views.patterns
: DefaultNone
. A list of URLs to inspect when generating the schema. IfNone
project’s URL conf will be used.generator_class
: Defaultrest_framework.schemas.SchemaGenerator
. May be used to specify aSchemaGenerator
subclass to be passed to theSchemaView
.authentication_classes
: Defaultapi_settings.DEFAULT_AUTHENTICATION_CLASSES
. May be used to pass custom authentication classes to theSchemaView
.permission_classes
: Defaultapi_settings.DEFAULT_PERMISSION_CLASSES
. May be used to pass custom permission classes to theSchemaView
.renderer_classes
: DefaultNone
. May be used to pass custom renderer classes to theSchemaView
. IfNone
theSchemaView
will be configured withDocumentationRenderer
andCoreJSONRenderer
renderers, corresponding to the (default)html
andcorejson
formats.
get_schemajs_view
¶
title
: DefaultNone
. May be used to provide a descriptive title for the schema definition.description
: DefaultNone
. May be used to provide a description for the schema definition.schema_url
: DefaultNone
. May be used to pass a canonical base URL for the schema.public
: DefaultTrue
. IfTrue
schema is generated without arequest
instance being passed to views.patterns
: DefaultNone
. A list of URLs to inspect when generating the schema. IfNone
project’s URL conf will be used.generator_class
: Defaultrest_framework.schemas.SchemaGenerator
. May be used to specify aSchemaGenerator
subclass to be passed to theSchemaView
.authentication_classes
: Defaultapi_settings.DEFAULT_AUTHENTICATION_CLASSES
. May be used to pass custom authentication classes to theSchemaView
.permission_classes
: Defaultapi_settings.DEFAULT_PERMISSION_CLASSES
May be used to pass custom permission classes to theSchemaView
.
Customising code samples¶
The built-in API documentation includes automatically generated code samples for each of the available API client libraries.
You may customise these samples by subclassing DocumentationRenderer
, setting languages
to the list of languages you wish to support:
from rest_framework.renderers import DocumentationRenderer
class CustomRenderer(DocumentationRenderer):
languages = ['ruby', 'go']
For each language you need to provide an intro
template, detailing installation instructions and such,
plus a generic template for making API requests, that can be filled with individual request details.
See the templates for the bundled languages for examples.