Skip to content
This repository has been archived by the owner on Nov 20, 2019. It is now read-only.
/ drf-autodocs Public archive

Ultimately automated DRF documentation rendering(UNMAINTAINED)

License

Notifications You must be signed in to change notification settings

iMakedonsky/drf-autodocs

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

71 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

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:

whole structure

Single node:

single node

Choices:

choices

Nested items:

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}
    """

help text

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:

extra_url_params

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:

url_name

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

buddhasoft

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