drf-pagination, coreapi automatically generates interface documents

Table of Contents

Pagination

The view class inherits the specific usage of paging from ListAPIView

# The first PageNumberPagination page number paging

# The second type of LimitOffsetPagination offset paging

# The third type of CursorPagination cursor paging

Use of view classes

The view class inherits the paging usage of APIView or GenericAPIView

coreapi

How to write good interface documentation

Automatically generate interface documentation

1 installation

2Set the interface document access path

3. The location of the document description

4Access interface documentation web page

5 notes

6 instructions

Page

Generally, paging needs to be used when checking all

# drf comes with three internal paging components, each with its own characteristics.
from rest_framework.pagination import PageNumberPagination,LimitOffsetPagination,CursorPagination

The view class inherits the specific paging method of ListAPIView

ListAPIView inherits GenericAPIView. In the GenericAPIView class, it is found that pagination_class = api_settings.DEFAULT_PAGINATION_CLASS, that is, the default source code paging class configuration is found from settings.py of drf, but ‘DEFAULT_PAGINATION_CLASS’ in drf’s configuration file: None, indicating that the initial paging class is None. That is, it is not used, so in the view class that inherits ListAPIView, we must configure the paging class through pagination_class( Component)

>>drf comes with three kinds of paging components. Generally, we use the first one, PageNumberPagination. Some parameters in each paging component (class) have default configurations, but we feel that its configuration is not applicable, so we should write our own paging class to inherit it and then modify its properties, which is the usage method

Note: Attributes should be changed according to needs. The following provided may not necessarily be used or changed in actual development. They are only for introduction.

# The first type ofPageNumberPagination page number paging

class MyLimitOffsetPagination(LimitOffsetPagination):
    default_limit = 3 # The number of items displayed per page defaults to api_settings.PAGE_SIZE
    limit_query_param = 'limit' # Get a few keywords from the benchmark. The default is limit.
    offset_query_param = 'offset' # Benchmark keyword defaults to offset. For example, start from 1 and get limit= so many numbers but do not include offset=.
    max_limit = 5 # Maximum limit per page Default = None means no limit
    # http: //127.0.0.1:8000/paging_test/?offset=3 & amp;limit=4 means starting from id=3 but taking id 4,5,6,7

# The second type of LimitOffsetPagination offset paging

class MyLimitOffsetPagination(LimitOffsetPagination):
    default_limit = 3 # The number of items displayed per page defaults to api_settings.PAGE_SIZE
    limit_query_param = 'limit' # Get a few keywords from the benchmark. The default is limit.
    offset_query_param = 'offset' # Benchmark keyword defaults to offset. For example, start from 1 and get limit= so many numbers but do not include offset=.
    max_limit = 5 # Maximum limit per page Default = None means no limit
    # http: //127.0.0.1:8000/paging_test/?offset=3 & amp;limit=4 means starting from id=3 but taking id 4,5,6,7

# The third type ofCursorPagination cursor paging

class MyCursorPagination(CursorPagination):
    cursor_query_param = 'cursor' # Cursor query keyword
    page_size = 3 #The number of items per page defaults to api_settings.PAGE_SIZE
    ordering = '-id' # Sort by, this is id descending order. The default is -created, which is the latest creation time.

"""
This type is generally suitable for paging with a large amount of data and is highly efficient because it does not have page number jumps like the first and second types.
And only the previous and next page buttons
Because it is displayed after sorting by ordering, the cursor indicates the position to query. The cursor value is something similar to a position index. For example, the following is the automatically generated URL route after clicking the next page on the first page.
# http: //127.0.0.1:8000/paging_test/?cursor=cD01
This only supports up and down pages, and does not support page number jumps. The page number jump requires re-searching every time, and the efficiency is not as high as this, but the page number jump is more user-friendly (each has its own pros and cons)
"""

Usage of view classes

class PublishListAPIViewTestPagination(ListAPIView):
    queryset = models.Publish.objects.all()
    serializer_class = PublishSerializers
    # Pagination class configuration pagination_class
    # pagination_class = MyPageNumberPagination # The first type
    # pagination_class = MyLimitOffsetPagination # The second type
    # pagination_class = MyCursorPagination # The third type

PS: The page_size of the three paging methods can be configured globally in settings.py, such as ‘PAGE_SIZE’:3, or written in REST_FRAMEWORK={ }

The view class inherits APIVieworGenericAPIView Use paging

We should also be able to write paging of view classes based on APIView or GenericAPIView, because this kind of controllability is high.

The specific use is to study the method calls in the source code of the three paging components.

coreapi

How to write good interface documents

There are many examples of interface document specifications on the Internet. After joining the company, the company will also have its own specifications.

For example, Weibo API: https://open.weibo.com/wiki/Weibo API

Automatically generate interface documents

REST_FRAMEWORK can automatically generate interface documents for us, and the interface documents are presented in the form of web pages.

Note: Automatic interface documentation can only generate views whose view classes inheritAPIView and its subclasses!!!

1Install

Use coreapi: pip3 install coreapi

2Set the interface document access path

Add interface document to the total route to access route configuration

The parameter title is the interface document website

from rest_framework.documentation import include_docs_urls
urlpatterns = [
…
path('docs/', include_docs_urls(title = 'Interface document site title'))
]

3The location of the document description

1. For single-method views, you can directly use the documentation string of the class view, such as:
class BookAPIView(ListAPIView):
"""
Return all book information
"""
2. A view that contains multiple methods is defined by method in the documentation string of the class view, such as:
class BookAPIView(ListCreateAPIView):
"""
get:
Return all book information
post:
New book
"""
3. For viewsets..ViewSet, they are still defined separately in the documentation string of the class, but should be distinguished by action names, such as
class BookViewSet(ListModelMixin, RetrieveModelMixin, GenericViewSet):
"""
list:
Return book list data
retrieve:
Return book details data
latest:
Return the latest book data
read:
Modify the reading volume of a book
"""

4 Access Interface Documentation Web Page

Enter the…/docs/route configured in the route to see the automatically generated interface document web page.

5Note

If you encounter the following error:
# AttributeError: 'AutoSchema' objects has no attribute 'get_link'
It should be a version issue. Older versions use rest_framework.schemas.openapi.AutoSchema by default.
Solution: Reconfigure in REST_FRAMEWORK
REST_FRAMEWORD = {
'DEFAULT_SCHEMA_CLASS':'rest_framework.schemas.coreapi.AutoSchema'
}

6Description

The knowledge points of the article match the official knowledge files, and you can further learn relevant knowledge. Python entry skill treeWeb application development Django383135 people are learning the system