THIS REPO IS NO LONGER MAINTAINED. PLEASE CONSIDER OTHER AUTOMATED DOCUMENTATION PACKAGES

Django REST framework auto docs

Automated api documentation renderer

Features:

optional response_serializer_class, if output serializer is different from input serializer
fully-documented functional views
tree-like structure
Docstrings:
markdown
preserve space & newlines
formatting with nice syntax
Fields:
different fields for request/response, based on read-/write-only attributes and whether response_serializer_class presented or not
choices rendering
help_text rendering (to specify SerializerMethodField output, etc)
Endpoint properties:
filter_backends
authentication_classes
permission_classes
extra url params(GET params)

What isn't supported yet:

viewsets
possibility to try in browser

Samples

Whole structure:

Single node:

Choices:

Nested items:

Docstring formatting:

@format_docstring(request_example, response_example=response_example)
class BookReadUpdateHandler(RetrieveUpdateAPIView):
    """
    Wow, this magic decorator allows us to:
        1) Keep clean & short docstring
        2) Insert additional data in it, like request/response examples

    Request: {}
    Response: {response_example}
    """

Installation

In virtualenv:

pip install drf_autodocs

In settings:

INSTALLED_APPS = [
    ...
    'drf_autodocs',
    ...
]

In your urls:

urlpatterns = [
    ...
    url(r'^', include('drf_autodocs.urls')),
]

That's already enough for swagger-like docs, result available on

localhost:8000/docs/

If you want functional views support and some more features, read below.

Usage

Tree-like structure

Tree-like structure is built from url prefixes. To make your endpoints grouped by some category, you must include your urls within other url. There are, generally, 2 ways to achieve it:

Example 1:

university_urlpatterns = [
    url(r'^lecturers/', university_views.LecturersHandler.as_view(), name='lecturers'),
    url(r'^lecturers/(?P<pk>\d+)/$', university_views.LecturerUpdateHandler.as_view(), name='lecturer_read_update'),
    url(r'^universities/', university_views.UniversitiesHandler.as_view(), name='universities'),
]

urlpatterns = [
    url(r'^library/', include(library_urlpatterns, namespace='library')),
    url(r'^university/', include(university_urlpatterns, namespace='university')),
]

Example 2:

urlpatterns = [
    url(r'^library/', include(library_urlpatterns, namespace='library')),
    url(r'^university/', include([
        url(r'^lecturers/', university_views.LecturersHandler.as_view(), name='lecturers'),
        url(r'^lecturers/(?P<pk>\d+)/$', university_views.LecturerUpdateHandler.as_view(), name='lecturer_read_update'),
        url(r'^universities/', university_views.UniversitiesHandler.as_view(), name='universities')
    ], namespace='university')),
]

Response serializer class

Say you have a view like this:

class BookReadUpdateHandler(RetrieveUpdateAPIView):
    serializer_class = BookUpdateSerializer
    queryset = Book.objects.all()

And say this serializers' input is different from output:

class BookUpdateSerializer(serializers.ModelSerializer):
    class Meta:
        fields = ('name', 'author')
        model = Book

    def to_representation(self, instance):
        return LibrarySerializer(instance.library)

Now to know what return format is, one must make a request. This package simplifies it via:

response_serializer_class = YourSerializer

Now your view looks like:

class BookReadUpdateHandler(RetrieveUpdateAPIView):
    """
    Shiny and nice docstring, which:
        1) allows formatting
        2) `allows markdown`
    """
    serializer_class = BookUpdateSerializer
    response_serializer_class = LibrarySerializer
    queryset = Book.objects.all()

Docstring formatting in class-based views

from .request_response_examples import request_example, response_example
from drf_autodocs.decorators import format_docstring


@format_docstring(request_example, response_example=response_example)
class BookReadUpdateHandler(RetrieveUpdateAPIView):
    """
    Wow, this magic decorator allows us to:
        1) Keep clean & short docstring
        2) Insert additional data in it, like request/response examples

    Request: {}
    Response: {response_example}
    """
    serializer_class = BookUpdateSerializer
    response_serializer_class = LibrarySerializer
    queryset = Book.objects.all()

Extra URL(GET) parameters

Please think twice before using such parameters, as they might be unneeded.

But if you really need them, here you go:

class LibrariesHandler(ListCreateAPIView):
    """
    Shiny and nice docstring, which:
        1) allows formatting
        2) `allows markdown`
    """
    extra_url_params = (('show_all', 'Bool', 'if True returns all instances and only 5 otherwise'),
                        ('some_extra_param', 'Integer', 'Something more to be included there'))

Results in:

Function-based views

For functional views, decorate them with.

drf_autodocs.decorators.document_func_view

Now you can insert into view via kwargs:

serializer_class
response_serializer_class
filter_backends
authentication_classes
permission_classes
doc_format_args
doc_format_kwargs

Now it should look like:

from drf_autodocs.decorators import document_func_view

format_args = ['"This string\nwas inserted"',]

@document_func_view(serializer_class=BookSerializer,
                    response_serializer_class=LibrarySerializer,
                    doc_format_args=format_args)
@api_view(['GET', 'POST', 'DELETE'])
def hello_world(request):
    """
    Works for `functional` views too!
        Yeah, that thing rocks!
        And allows formatting {}
    """
    return Response('hello_world response')

Help text

This package uses default DRF field attribute help_text If you're using ModelSerializer, and model field got help_text attr, it will be transferred to your serializers' field automatically.

Example:

from rest_framework import serializers

has_books = serializers.SerializerMethodField(help_text='returns Bool')

Note that specifying help_text on serializers' field overrides the one from model

Customization

To change application look & feel, override templates and/or static files.

Root template is : templates/drf_autodocs/index.html

For additional parsers(if you want other structure than tree), inherit from

drf_autodocs.parser.BaseAPIParser

Configuration/settings

Endpoint names could use view names or url names, replacing '_' and '-' with ' ' and capitalizing output.

Default behavior is to use url names:

url(r'^books/(?P<pk>\d+)/$', library_views.BookReadUpdateHandler.as_view(), name='book_read_update'),

will result in:

If you want to use endpoint(view) names instead, do this in settings:

AUTODOCS_ENDPOINT_NAMES = "view"

Supports

Python 3
Django 1.8+
Django Rest Framework 3+

Credits

Thanks to django, django-REST for their awesome work, and drf-docs for source of inspiration as well as some parts of code.

Developed with care by Mashianov Oleksander at

If you 👍 this, don't forget to ⭐ it and share with friends.

iMakedonsky/drf-autodocs