[Django REST framework - 自动生成接口文档、分页]

[Django REST framework - 自动生成接口文档、分页]

自动生成接口文档

# 后端人员写好接口，编写接口文档，给前端人员看，前端人员依照接口文档开发

# 公司里主流
	-后端，使用world，md写，提到git上
    -公司有接口平台，后端开发在接口平台录入（yapi，第三方），可以批量导入
    -后端项目自动生成接口文档（不是特别美观或友好，有时候还需要配合上面两种）
    	-django的drf自动生成  coerapi，swagger：java，go，python

REST framework可以自动帮助我们生成接口文档。

接口文档以网页的方式呈现。

自动接口文档能生成的是继承自APIView及其子类的视图。

接口文档 coreapi，swagger
​
安装依赖：REST framewrok生成接口文档需要coreapi库的支持。
    pip3 install coreapi
 
使用步骤：
​
1 在urls.py 路由中
    from rest_framework.documentation import include_docs_urls
​
    urlpatterns = [
     path('doc/', include_docs_urls(title='图书管理项目接口文档')),
    ]
    
2 在settings.py 配置文件中
    REST_FRAMEWORK = {
    'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.coreapi.AutoSchema',
    }
    
3 在view.py 视图类中对应的方法上加注释即可
    
4 如果是ModelViewSet
   from app01 import models
    from app01 import serializer
    from rest_framework.viewsets import ModelViewSet
    from rest_framework.filters import OrderingFilter
​
class BookView(ModelViewSet):
    """
      list:
      返回图书列表数据，通过Ordering字段排序
​
      retrieve:
      返回图书详情数据
​
      latest:
      返回最新的图书数据
​
      read:
      查询单个图书接口
    """
    queryset = models.Book.objects.all()
    serializer_class = serializer.BookModelSerializer
    # 排序
    filter_backends = [OrderingFilter,]
    ordering_fields = ['price','name']
    
    
5 字段描述，写在models.py的help_text上
from django.db import models
​
class Book(models.Model):
    name = models.CharField(max_length=34,help_text='名字字段，字符串')
    price = models.IntegerField(help_text='价格字段，整型')
​
6 浏览的地址（浏览器中）
    http://127.0.0.1:8000/doc/
            
# 如果继承的是其它视图类，直接在对应的def函数下面写注释即可，例：
class BookView(APIView):
    def get(self, request):
        """
        所有图书信息
        :param request: 
        :return: 
        """
        res = models.Book.objects.all()
        ser = serializer.BookModelSerializer(instance=res, many=True)
        return Response(ser.data)

分页Pagination

REST framework提供了分页的支持。可选分页器有三种

三种分页方式

1 三种分页方式
 -基本分页：PageNumberPagination
    page_size = 2  # 每页显示两条
    page_query_param = 'page'  #查询第几页的参数 ?page=3
    max_page_size = 4     #每页最大显示多少条
    page_size_query_param = 'size' #每页显示的条数查询条件（默认是page_size显示的条数） # ?page=3&size=3
    
    
 -偏移分页：LimitOffsetPagination
    default_limit=2  #默认显示几条
    limit_query_param='limit'   # ？limit=3   表示取3条
    offset_query_param = 'offset' #偏移  ?offset=5&limit=3    #从第5个位置开始，取3条数据
    max_limit = 5   #最多显示5条
    
    
 -游标分页：CursorPagination
    cursor_query_param = 'cursor' # 查询的key值
    page_size = 2  # # 每页显示两条
    ordering = 'id' # 按id字段排序
    
    
2 如何使用
   - APP下创建一个自定义py文件，eg：page.py
   - 在文件中写一个自定义分页类，继承三个之一，并重写类属性
   - 在视图类中配置
    class BookView(ViewSetMixin,ListAPIView,CreateAPIView):
             queryset = models.Book.objects.all()
         serializer_class = serializer.BookModelSerializer
         # 配置使用的分页类
         pagination_class = CustomNumberPagination
        
    - 局部使用
        pagination_class = CustomNumberPagination

    - 全局使用，在配置文件中（以后所有视图的查询所有方法都用这个分页）
        REST_FRAMEWORK = {
     'DEFAULT_PAGINATION_CLASS':'app01.page.CustomNumberPagination'  
    }

基本分页：PageNumberPagination

也是用的最多的一种

创建一个py文件  # 任意名字  例如:page.py

1、在page.py 中自定义一个类，继承PageNumberPagination，并重写类属性

from rest_framework.pagination import PageNumberPagination   # 导入模块

class CustomNumberPagination(PageNumberPagination):  # 定义类名继承父类  重写属性
    
    page_size = 2  # 每页显示两条
    page_query_param = 'page'  #查询第几页的参数 ?page=3

    max_page_size = 4     # 每页最大显示多少条
    page_size_query_param = 'size' #每页显示的条数查询条件（默认是page_size显示的条数） # ?page=2&size=3
    
    
2、在views.py 视图类中配置 
from rest_framework.generics import ListAPIView, CreateAPIView
from rest_framework.viewsets import ViewSetMixin
from app01.page import CustomNumberPagination # 导入自定义分页类

class BookView(ViewSetMixin,ListAPIView,CreateAPIView):
    queryset = models.Book.objects.all()
    serializer_class = serializer.BookModelSerializer
    
    # 配置使用的分页类
    pagination_class = CustomNumberPagination  # 自己定义的类名
    
4、请求方式：（postman中测试）   
    http://127.0.0.1:8000/books/?page=3  # 查第3页
    http://127.0.0.1:8000/books/?page=2&size=3  # 第2页显示3条
    
    
3、局部使用（视图类中）
    pagination_class = CustomNumberPagination

4、全局使用，在settings.py 配置文件中（以后所有视图的查询所有方法都用这个分页）
    REST_FRAMEWORK = {
 'DEFAULT_PAGINATION_CLASS':'app01.page.CustomNumberPagination'
}

偏移分页：LimitOffsetPagination

用的比较少的一种

1、在page.py 中自定义一个分页类，继承LimitOffsetPagination，并重写类属性

from rest_framework.pagination import LimitOffsetPagination  # 导入模块

class CustomLimitOffsetPagtion(LimitOffsetPagination):
    default_limit=2  # 默认显示几条
    limit_query_param='limit'   # ？limit=3   表示取3条
    offset_query_param = 'offset' #偏移  ?offset=5&limit=3   从第5个位置开始，取3条数据
    max_limit = 5   #最多显示5条
	# 手动写显示10条  也是显示5条 因为这已经写死了 
    
2、在views.py 视图类中配置 
from rest_framework.generics import ListAPIView, CreateAPIView
from rest_framework.viewsets import ViewSetMixin
from app01.page import CustomLimitOffsetPagtion # 导入自定义偏移分页类

class BookView(ViewSetMixin,ListAPIView,CreateAPIView):
    queryset = models.Book.objects.all()
    serializer_class = serializer.BookModelSerializer
    
    # 配置使用的分页类
    pagination_class = CustomLimitOffsetPagtion
    
4、请求方式：（postman中测试）   
    http://127.0.0.1:8000/books/  # 默认从0开始取2条
    http://127.0.0.1:8000/books/?limit=3&offset=2  # 取3条，从第2条开始
    
3、局部使用（视图类中）
    pagination_class = CustomLimitOffsetPagtion

4、全局使用，在settings.py 配置文件中（以后所有视图的查询所有方法都用这个分页）
    REST_FRAMEWORK = {
 'DEFAULT_PAGINATION_CLASS':'app01.page.CustomLimitOffsetPagtion'
}

游标分页：CursorPagination

基本不用，但针对千万级别的数据，为了降低数据库的压力，建议使用这种

1、在page.py 中自定义一个分页类，继承CursorPagination，并重写类属性
## 优点：速度最快，数据量越大，越有优势
## 缺点：只能前一页和后一页，不能直接跳到某一页

from rest_framework.pagination import CursorPagination

class CustomCursorPagination(CursorPagination): # 查询速度最快
    cursor_query_param = 'cursor' # 查询的key值
    page_size = 2  #  每页显示两条
    ordering = 'id' # 按id字段排序  必须写不然报错
    
    # 下面两个基本不用可配可不配
     page_size_query_param = 'size'   # 通过这个参数决定每页显示多少条 
  	 max_page_size = 5     # 每页最大显示多少条
    
2、在views.py 视图类中配置 
from rest_framework.generics import ListAPIView, CreateAPIView
from rest_framework.viewsets import ViewSetMixin
from app01.page import CustomCursorPagination # 导入自定义游标分页类

class BookView(ViewSetMixin,ListAPIView,CreateAPIView):
    queryset = models.Book.objects.all()
    serializer_class = serializer.BookModelSerializer
    # 配置使用的分页类
    pagination_class = CustomCursorPagination
    
4、请求方式：（postman中测试）   
    http://127.0.0.1:8000/books/?cursor=cD0y   # 按照cursor给的key值查找下一页
    http://127.0.0.1:8000/books/?cursor=cj0xJnA9Mw%3D%3D  # 按照cursor给的key值查找上一页
    
3、局部使用（视图类中）
    pagination_class = CustomCursorPagination

4、全局使用，在settings.py 配置文件中（以后所有视图的查询所有方法都用这个分页）
    REST_FRAMEWORK = {
 'DEFAULT_PAGINATION_CLASS':'app01.page.CustomCursorPagination'
}

继承APIView实现三种分页方式

class BookViewALL(APIView):   # 继承APIView   需要自己写路由

    def get(self,request,*args,**kwargs):
        book_list=Books.objects.all()
        #实例化得到一个对象
        pagination=CommonPageNumberPagination() # 只需要换此处的类就可以实现三种分页的效果
        
        # 修改对象属性，我们不需要改
        # pagination.page_query_param='page'

        #调用对象方法，传入要分页的数据，book_list,返回分页号的数据
        book_list2=pagination.paginate_queryset(book_list,request,self)

        ser=BookSerializer(instance=book_list2,many=True)  # 序列化器
        # 自己写返回格式
        res={'pre':pagination.get_previous_link(),'next':pagination.get_next_link(),'count':pagination.page.paginator.count,'data':ser.data}
        
        return Response(res)

        # 另一种返回方式 调用父类中的方法返回
        return pagination.get_paginated_response(ser.data)