Django中restful风格DRF自定义接口自定义传参文档注释问题

提示：文章写完后，目录可以自动生成，如何生成可参考右边的帮助文档

---

前言

提示：这里可以添加本文要记录的大概内容：

django的restful框架文档生成可参考doc文档生成
本篇主要记录restful自定义接口传参，以及文档注释的问题

提示：以下是本篇文章正文内容，下面案例可供参考

一、restful接口

restful是一种风格架构，每一个接口地址，代表了一种资源

1. GET（SELECT）：从服务器取出资源（一项或多项）。
2. POST（CREATE）：在服务器新建一个资源。
3. PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）。
4. DELETE（DELETE）：从服务器删除资源

二、自定义入参的自定义接口

1.在视图类下自定义方法，添加action

代码如下（示例）：

class ImportExcelViews(mixins.CreateModelMixin,
                       mixins.UpdateModelMixin,
                       mixins.DestroyModelMixin,
                       mixins.ListModelMixin,
                       GenericViewSet):
                       
	queryset = FileUpload.objects.all()  # 指明该视图集在查询数据时使用的查询集
    serializer_class = FileUploadSerializers  # 指明该视图在进行序列化或反序列化时使用的序列化器
    
    @action(methods=['get'], detail=False)
    def clean(self, request,  *args, **kwargs):
        clean_type = request.GET.get('clean_type', 1)  # 数据清洗类型
        id = request.GET.get('id')                     # 主键id

        instance = FileUpload.objects.filter(id=id).first()  # 模型对象

        file_path = os.path.join(base_dir, 'static', 'media', str(instance.file))
        df = pd.read_excel(file_path)
        df = df.dropna(axis=1)  # 清除掉为空的列

        if clean_type == 1:
            df = df.dropna(axis=0)
        elif clean_type == 2:
            for column in list(df.columns[df.isnull().sum() > 0]):
                mean_val = df[column].mean()
                df[column].fillna(mean_val, inplace=True)
        res = df.to_dict()

        return Response(res)

此时，自定义接口就已经成功了
打开docs,可以看到接口已经存在，但是并没有入参和文档注释

2.添加文档注释

添加文档注释：

class ImportExcelViews(mixins.CreateModelMixin,
                       mixins.UpdateModelMixin,
                       mixins.DestroyModelMixin,
                       mixins.ListModelMixin,
                       GenericViewSet):
    """
    list:
        获取原始数据集列表信息
    create:
        上传数据集文件
    delete:
        删除原始数据集
    update:
        修改上传数据集内容
    clean_data:
        样本清洗
    details:
        统计样本详情以及缺失值情况
    partial_update:
        修改单个属性值接口
    """

给视图类添加文档注释，打开docs，可以看到接口注释已成功添加

3.给自定义接口添加自定义参数

首先自定义一个Schema：

# 在接口中添加自定义请求字段
cleanSchema = ManualSchema(
    fields=[
        coreapi.Field(name="id", required=True, location="query", schema=coreschema.Integer(description="主键id")),
        coreapi.Field(name="clean_type", required=False, location="query", schema=coreschema.Enum(enum=[1, 2], description="清洗方式(1:删除, 2:填充均值)"))
    ]
)

然后再action中添加自定义schema

此时打开docs,发现参数已经出现，但接口注释却消失了

此时再在schema中添加一个description字段

cleanSchema = ManualSchema(
    description='清洗数据集',
    fields=[
        coreapi.Field(name="id", required=True, location="query", schema=coreschema.Integer(description="主键id")),
        coreapi.Field(name="clean_type", required=False, location="query", schema=coreschema.Enum(enum=[1, 2], description="清洗方式(1:删除, 2:填充均值)"))
    ]
)

打开docs,接口注释已出现

测试接口，调用成功：

总结