项目作者: iMakedonsky

项目描述 :
Ultimately automated DRF documentation rendering(UNMAINTAINED)
高级语言: HTML
项目地址: git://github.com/iMakedonsky/drf-autodocs.git
创建时间: 2016-12-24T11:09:28Z
项目社区:https://github.com/iMakedonsky/drf-autodocs

开源协议:BSD 2-Clause "Simplified" License

下载


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:

  1. @format_docstring(request_example, response_example=response_example)
  2. class BookReadUpdateHandler(RetrieveUpdateAPIView):
  3. """
  4. Wow, this magic decorator allows us to:
  5. 1) Keep clean & short docstring
  6. 2) Insert additional data in it, like request/response examples
  7. Request: {}
  8. Response: {response_example}
  9. """

help text

Installation

In virtualenv:

  1. pip install drf_autodocs

In settings:

  1. INSTALLED_APPS = [
  2. ...
  3. 'drf_autodocs',
  4. ...
  5. ]

In your urls:

  1. urlpatterns = [
  2. ...
  3. url(r'^', include('drf_autodocs.urls')),
  4. ]

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:

  1. university_urlpatterns = [
  2. url(r'^lecturers/', university_views.LecturersHandler.as_view(), name='lecturers'),
  3. url(r'^lecturers/(?P<pk>\d+)/$', university_views.LecturerUpdateHandler.as_view(), name='lecturer_read_update'),
  4. url(r'^universities/', university_views.UniversitiesHandler.as_view(), name='universities'),
  5. ]
  6. urlpatterns = [
  7. url(r'^library/', include(library_urlpatterns, namespace='library')),
  8. url(r'^university/', include(university_urlpatterns, namespace='university')),
  9. ]

Example 2:

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

Response serializer class

Say you have a view like this:

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

And say this serializers’ input is different from output:

  1. class BookUpdateSerializer(serializers.ModelSerializer):
  2. class Meta:
  3. fields = ('name', 'author')
  4. model = Book
  5. def to_representation(self, instance):
  6. 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:

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

Docstring formatting in class-based views

  1. from .request_response_examples import request_example, response_example
  2. from drf_autodocs.decorators import format_docstring
  3. @format_docstring(request_example, response_example=response_example)
  4. class BookReadUpdateHandler(RetrieveUpdateAPIView):
  5. """
  6. Wow, this magic decorator allows us to:
  7. 1) Keep clean & short docstring
  8. 2) Insert additional data in it, like request/response examples
  9. Request: {}
  10. Response: {response_example}
  11. """
  12. serializer_class = BookUpdateSerializer
  13. response_serializer_class = LibrarySerializer
  14. 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:

  1. class LibrariesHandler(ListCreateAPIView):
  2. """
  3. Shiny and nice docstring, which:
  4. 1) allows formatting
  5. 2) `allows markdown`
  6. """
  7. extra_url_params = (('show_all', 'Bool', 'if True returns all instances and only 5 otherwise'),
  8. ('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:

  1. from drf_autodocs.decorators import document_func_view
  2. format_args = ['"This string\nwas inserted"',]
  3. @document_func_view(serializer_class=BookSerializer,
  4. response_serializer_class=LibrarySerializer,
  5. doc_format_args=format_args)
  6. @api_view(['GET', 'POST', 'DELETE'])
  7. def hello_world(request):
  8. """
  9. Works for `functional` views too!
  10. Yeah, that thing rocks!
  11. And allows formatting {}
  12. """
  13. 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:

  1. from rest_framework import serializers
  2. 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 :thumbsup: this, don’t forget to :star: it and share with friends.