drf-分页，coreapi自动生成接口文档

目录

分页

 视图类继承ListAPIView的分页具体使用方法 

# 第一种PageNumberPagination页码分页

# 第二种LimitOffsetPagination偏移分页

# 第三种CursorPagination游标分页

视图类的使用

视图类继承APIView或GenericAPIView的分页使用

coreapi

如何写好接口文档

自动生成接口文档

1安装

2设置接口文档访问路径

3文档描述说明的位置

4访问接口文档网页

5注

6说明

---

分页

一般查所有时需要使用到分页,所以我们这写视图类继承的是ListAPIView,但可控性低，后续视项目需求而定

# drf内部自带三种分页组件，各有各的特点
from rest_framework.pagination import PageNumberPagination,LimitOffsetPagination,CursorPagination

 视图类继承ListAPIView的分页具体使用方法 

ListAPIView继承了GenericAPIView，在GenericAPIView类中发现pagination_class = api_settings.DEFAULT_PAGINATION_CLASS即默认源码分页类配置是从drf的settings.py中找的，但drf的配置文件中'DEFAULT_PAGINATION_CLASS': None,表示初始分页类为None即未使用，所以在继承了ListAPIView的视图类中我们要通过pagination_class来配置分页类(组件)

>>drf内部自带了三种分页组件，一般我们都用第一个即PageNumberPagination。每个分页组件(类)中有些参数有默认配置但我们觉得它的配置不适用，所以我们应该写自己的分页类来继承它然后修改其中的属性，即为使用方法

注：属性应根据需求来改，以下提供的实际开发中不一定都要用到或都要改，仅为了介绍

# 第一种PageNumberPagination页码分页

class MyLimitOffsetPagination(LimitOffsetPagination):
    default_limit = 3 # 每页展示条数 默认为api_settings.PAGE_SIZE
    limit_query_param = 'limit' # 从标杆后拿几条的关键字 默认为limit
    offset_query_param = 'offset' # 标杆关键字 默认为offset 比如从1开始拿limit=那么多条但不包含offset=的数字
    max_limit = 5 # 每页最大限制 默认= None即无限制
    # http: //127.0.0.1:8000/paging_test/?offset=3&limit=4即表示从id=3开始拿但拿的是id为4,5,6,7的

# 第二种LimitOffsetPagination偏移分页

class MyLimitOffsetPagination(LimitOffsetPagination):
    default_limit = 3 # 每页展示条数 默认为api_settings.PAGE_SIZE
    limit_query_param = 'limit' # 从标杆后拿几条的关键字 默认为limit
    offset_query_param = 'offset' # 标杆关键字 默认为offset 比如从1开始拿limit=那么多条但不包含offset=的数字
    max_limit = 5 # 每页最大限制 默认= None即无限制
    # http: //127.0.0.1:8000/paging_test/?offset=3&limit=4即表示从id=3开始拿但拿的是id为4,5,6,7的

# 第三种CursorPagination游标分页

class MyCursorPagination(CursorPagination):
    cursor_query_param = 'cursor' # 游标查询关键字
    page_size = 3 # 每页条数 默认为api_settings.PAGE_SIZE
    ordering = '-id' # 按什么排序,这为id降序 默认为-created即创建时间的最近
 
"""
	这种一般适用于数据量极大的分页，效率高，因为这种不像第一第二种一样有分页码跳转
	而只有上下页按钮
	因为它按ordering排序了后才展示，通过cursor游标指示了位置来查询，cursor值就是一个类似位置索引的东西，比如下面就是在第一页点击了下一页后自动生成的url路由
	# http: //127.0.0.1:8000/paging_test/?cursor=cD01
	这种只支持上下页，不支持分页码跳转。分页码跳转的每次都需重新检索，效率没有这个高，但分页码的那种可跳转比较人性化(各有利弊)
"""

视图类的使用

class PublishListAPIViewTestPagination(ListAPIView):
    queryset = models.Publish.objects.all()
    serializer_class = PublishSerializers
    # 分页类配置pagination_class
    # pagination_class = MyPageNumberPagination    # 第一种
    # pagination_class = MyLimitOffsetPagination  # 第二种
    # pagination_class = MyCursorPagination           # 第三种

PS：三种分页方式的page_size可以在settings.py中全局配置比如'PAGE_SIZE':3，还是写在REST_FRAMEWORK={ }中

视图类继承APIView或GenericAPIView的分页使用

视图类基于APIView或GenericAPIView的分页我们也应会写，因为这种可控性高

具体使用就是研究那三种分页组件源码里面的方法调用即可

coreapi

如何写好接口文档

网上有很多接口文档规范示例，进公司后也有公司相应自己的规范

比如微博api：  https://open.weibo.com/wiki/%E5%BE%AE%E5%8D%9AAPI

自动生成接口文档

REST_FRAMEWORK可以自动帮我们生成接口文档，接口文档以网页的方式呈现

注意：自动接口文档只能生成视图类是继承APIView及其子类的视图!!!

1安装

使用coreapi：pip3 install coreapi

2设置接口文档访问路径

在总路由中添加接口文档访问路由配置

参数title是接口文档网站

from rest_framework.documentation import include_docs_urls
urlpatterns = [
	…
	path('docs/', include_docs_urls(title = '接口文档站点标题'))
]

3文档描述说明的位置

1、单一方法的视图，可直接使用类视图的文档字符串，如：
	class BookAPIView(ListAPIView):
		"""
		返回所有图书信息
		"""
2、包含多个方法的视图，在类视图的文档字符串中分方法定义，如：
	class BookAPIView(ListCreateAPIView):
		"""
		get:
		返回所有图书信息
		post:
		新建图书
		"""
3、对于视图集..ViewSet那种，仍在类的文档字符串中分开定义，但应用action名称区分，如
	class BookViewSet(ListModelMixin, RetrieveModelMixin, GenericViewSet):
		"""
		list:
		返回图书列表数据
		retrieve:
		返回图书详情数据
		latest:
		返回最新图书数据
		read:
		修改图书的阅读量
		"""

4访问接口文档网页

输入路由中配置的…/docs/路由即可看到自动生成的接口文档网页

5注

如果遇到以下报错：
	# AttributeError: 'AutoSchema' objects has no attribute 'get_link'
应该是版本问题，旧版默认用的rest_framework.schemas.openapi.AutoSchema
解决办法：在REST_FRAMEWORK中重配置
REST_FRAMEWORD = {
	'DEFAULT_SCHEMA_CLASS':'rest_framework.schemas.coreapi.AutoSchema'
}

6说明