drf Framework Document Interface

0922 self-summary

drf Framework Document Interface

REST framework can help us to automatically generate the interface documentation.

Interface documentation presented by way of a web page.

Automatic generation of interface documentation can be inherited from APIViewview and its subclasses.

A. Installation depends

pip install coreapi

II. Setting the interface document access path

Adding interface documentation path in the overall route.

Document routing configuration corresponding to the view rest_framework.documentation.include_docs_urls,

Parameters titlefor the title interface documentation site.

from rest_framework.documentation import include_docs_urls

urlpatterns = [
    ...
    path('docs/', include_docs_urls(title='站点页面标题'))
]

III. Documentation describing the definition of the position description

Documentation string view, view class may be used as 1) a single process, such as

class BookListView(generics.ListAPIView):
    """
    返回所有图书信息.
    """

2) a method comprising a plurality of views, the view of the document string class, method defined separately, such as

class BookListCreateView(generics.ListCreateAPIView):
    """
    get:
    返回所有图书信息.

    post:
    新建图书.
    """

3) For set Viewset view, the document view of the string class are still closed to open is defined, it is to be used to distinguish the name of action, such as

class BookInfoViewSet(mixins.ListModelMixin, mixins.RetrieveModelMixin, GenericViewSet):
    """
    list:
    返回图书列表数据

    retrieve:
    返回图书详情数据

    latest:
    返回最新的图书数据

    read:
    修改图书的阅读量
    """

IV. Access Interface Documentation Web page

There are two points to note

1) View Set ViewSet retrieve the name, called the read document interface site

2) Description of parameters need to be defined in the model options help_text class or classes of sequences of fields, such as:

class BookInfo(models.Model):
    ...
    bread = models.IntegerField(default=0, verbose_name='阅读量', help_text='阅读量')
    ...

or

class BookReadSerializer(serializers.ModelSerializer):
    class Meta:
        model = BookInfo
        fields = ('bread', )
        extra_kwargs = {
            'bread': {
                'required': True,
                'help_text': '阅读量'
            }
        }