【DRF配置管理】如何建立coreapi风格接口文档

原文作者：我辈李想
版权声明：文章原创，转载时请务必加上原文超链接、作者信息和本声明。

DRF应用和管理

【DRF配置管理】Django安装DRF框架并生成openapi风格文档
【DRF配置管理】如何实现JWT身份验证
【DRF配置管理】如何使用序列化:验证码、注册和登录
【DRF配置管理】如何结合ORM实现排序、模糊搜索、范围查询
【DRF配置管理】如何在视图类使用get_objects()
【DRF配置管理】如何实现RBAC页面菜单和按钮权限
【DRF配置管理】如何建立coreapi风格api接口文档
【DRF配置管理】如何建立swagger风格api接口文档

---

---

前言

DRF广泛的应用于django网络开发，尤其是在前后端分离的项目中，与vue、react等框架结合使用。本篇博客单独介绍DRF自带接口文档的使用。

---

一、coreapi安装

这个库需要安装。

pip install coreapi

二、REST_FRAMEWORK参数

REST_FRAMEWORK = {
    'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.coreapi.AutoSchema',
   'DEFAULT_AUTHENTICATION_CLASSES': [
	    # 自己写的认证类
	    'studentSystemt.apps.user.authen.MyJWTAuthentication'
    ],
}

三、urls路由配置

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

四、视图注释显示

这里的注释一般是在类视图，主要跟继承的方法有关，本博客以ModelViewSet为例，示例如下:

class PicDatasView(ModelViewSet):
    """
    list:
    不带路径参数获取全部
    create:
    新增一条记录
    retrieve:
    带路径参数获取一条
    update:
    带路径参数更新一条
    destroy:
    带路径参数删除一条
    """
    def list(self, request):
    	pass

五、请求参数显示

这里的请求参数包含两部分，第一种models参数,是使用序列化的字段参数，也是models模型的字段，第二种就是自定义参数，一般数为了后端判断，或者批量操作的列表参数等。

1.models参数

这种参数可以通过设置字段的help_text来实现，主要用于创建和修改。

models.py文件

class HistoryData(models.Model):
    id = models.AutoField(primary_key=True, help_text='历史区域的主键id')
    
    geometrycollection = models.GeometryCollectionField('混合数据', null=True, help_text='空间混合数据')

serializer.py文件

class HistoryDataSerializer(GeoModelSerializer):
    """
    目标区域
    """
    hid = serializers.IntegerField(source="id", read_only=True)

    class Meta:
        model = HistoryData
        fields = ['hid', 'name', 'user_id', 'type', 'point', 'diameter', 'geometrycollection']

2.自定义参数

自定义参数需要我们自己设置，主要用于list(getall)的查询和文件下载。schema 参数对整个类视图生效。

views.py文件

import coreapi
import coreschema
from rest_framework.schemas import ManualSchema

class KmlDownload(ModelViewSet):
    """
    list:下载文件：kml
    """
    serializer_class = KmlDownloadSerializer
    # 认证
    authentication_classes = [IsAuthentication]
    # docs文档参数
    schema = ManualSchema(
        description='下载文件：kml',
        fields=[
            coreapi.Field(name="hid", required=True, location="query",
                          schema=coreschema.Integer(description="历史区域主键id")),
            coreapi.Field(name="pids", required=True, location="query",
                          schema=coreschema.Array(description="影像数据主键id的列表[1,2,3,4]"))
        ]
    )

    def list(self, request):
        pass

六、自定义action文档

action装饰器方法可以重新设置类视图的参数，第五部中的schema参数对全部方法有效，但是有些时候我们并不希望这样，我们希望对指定方法生效，就需要用action。这里面有一个坑，就是如果想用action，urls路由必须使用drf的routers。

urls.py文件如下：

from django.urls import path
from rest_framework import routers

urlpatterns = [
	...
    # path('picdatas/', views.PicDatasView.as_view({'get': 'list'})),  # 网站影像查询
    # path('picdatas/<int:pk>/', views.PicDatasView.as_view({'delete': 'destroy'})),  # 网站影像查询
    # path('picdatas/<int:pk>/dw/', views.PicDatasView.as_view({'get': 'dw'})),  # 网站影像查询
]

router = routers.SimpleRouter()
router.register(r'picdatas', views.PicDatasView)
urlpatterns += router.urls

views.py文件如下：

import coreapi
import coreschema
from rest_framework.decorators import action
from rest_framework.schemas import ManualSchema
from rest_framework.viewsets import ModelViewSet

class KmlDownload(ModelViewSet):
    """
    dw:下载文件：kml
    """
    serializer_class = KmlDownloadSerializer
    # 认证
    authentication_classes = [IsAuthentication]

	# 在接口中添加自定义请求字段
	dw_schema = ManualSchema(
			description='根据筛选条件实现查询',
	        fields=[
	            coreapi.Field(name="hid", required=True, location="query",
	                          schema=coreschema.Integer(description="历史区域主键id")),
	            coreapi.Field(name="pids", required=True, location="query",
	                          schema=coreschema.Array(description="影像数据主键id的列表[1,2,3,4]"))
	        ]
	)	

	@action(methods=['get'], detail=False,schema=dw_schema)
    def dw(self, request):
    	...
        pass