drf-分页,coreapi自动生成接口文档
目录
# 第二种LimitOffsetPagination偏移分页
视图类继承APIView或GenericAPIView的分页使用
分页
一般查所有时需要使用到分页,所以我们这写视图类继承的是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说明