django配置swagger自动生成接口文档以及自定义参数设置

　　首先安装swagger所用的包

pip install drf-yasg

　　然后再settings.py 中注册app

　　接口采用的token认证，在settings.py配置认证方式

SWAGGER_SETTINGS = {
    'USE_SESSION_AUTH': False,
    'SECURITY_DEFINITIONS': {
        '身份验证': {
            'type': 'apiKey',
            'in': 'header',
            'name': 'Authorization'
        }
    },
}

　　配好后打开的认证是这样的

　　在urls.py中配置路由

from django.contrib import admin
from django.urls import path, include

# 使用 drf_yasg API文档生成器 视图和openapi
from django.views.static import serve
from drf_yasg.views import get_schema_view
from drf_yasg import openapi

# 导入权限控制模块
from rest_framework import permissions

# 文档视图
schema_view = get_schema_view(
    # API 信息
    openapi.Info(
        title='接口文档',   # API文档标题
        default_version='V1',   # 版本信息
        description='接口文档',    # 描述内容
        # terms_of_service='https://qaq.com',    # 开发团队地址
        # contact=openapi.Contact(email='https://[email protected]',url='https://qaq.com'),   # 联系人信息：邮件、网址
        # license=openapi.License(name='qaq License'),    # 证书
    ),
    public=True,    # 是否公开
    # permission_classes=(permissions.AllowAny,)   # 设置用户权限

)

urlpatterns = [
    path('admin/', admin.site.urls),

    path('userManage/', include('userManage.urls')),
    path('ani/', include('ani.urls')),

    path('swagger/', schema_view.with_ui('swagger', cache_timeout=0), name='schema-swagger-ui'),   # 互动模式
    path('redoc/', schema_view.with_ui('redoc', cache_timeout=0), name='schema-redoc'),   # 文档模式
]

　　配置好以后打开  http://127.0.0.1:8000/swagger/即可访问到接口文档页面

　　打开查看后发现，请求的参数缺少了，返回的参数和接口实际返回的参数不一样，因为我的视图继承APIView做了一些自定义的请求参数和返回参数。

　　所以需要自定义swagger

　　util.py文件，因为自动生成的采用序列化 query_serializer参数就会将一些外键的source字段也加到参数里面，所以重新去获取序列器的字段。再定义一个

　　固定格式的基类

from rest_framework import serializers
from drf_yasg import openapi
from rest_framework.relations import PrimaryKeyRelatedField
from rest_framework.fields import ChoiceField


def serializer_to_swagger(ser_model, get_req=False):
    '''
    将序列化字段转成openapi的形式
    '''
    if ser_model is None and get_req is True:
        return {}, []
    elif ser_model is None and get_req is False:
        return {}
    dit = {}
    serializer_field_mapping = {
        ChoiceField: openapi.TYPE_INTEGER,
        PrimaryKeyRelatedField: openapi.TYPE_INTEGER,
        serializers.IntegerField: openapi.TYPE_INTEGER,
        serializers.BooleanField: openapi.TYPE_BOOLEAN,
        serializers.CharField: openapi.TYPE_STRING,
        serializers.DateField: openapi.TYPE_STRING,
        serializers.DateTimeField: openapi.TYPE_STRING,
        serializers.DecimalField: openapi.TYPE_NUMBER,
        serializers.DurationField: openapi.TYPE_STRING,
        serializers.EmailField: openapi.TYPE_STRING,
        serializers.ModelField: openapi.TYPE_OBJECT,
        serializers.FileField: openapi.TYPE_STRING,
        serializers.FloatField: openapi.TYPE_NUMBER,
        serializers.ImageField: openapi.TYPE_STRING,
        serializers.SlugField: openapi.TYPE_STRING,
        serializers.TimeField: openapi.TYPE_STRING,
        serializers.URLField: openapi.TYPE_STRING,
        serializers.UUIDField: openapi.TYPE_STRING,
        serializers.IPAddressField: openapi.TYPE_STRING,
        serializers.FilePathField: openapi.TYPE_STRING,
    }
    fields = ser_model().get_fields()
    if get_req:
        required = []
        for k, v in fields.items():
            description = getattr(v, 'label', '')
            if isinstance(v, serializers.SerializerMethodField) or getattr(v, 'source'):
                continue
            elif isinstance(v, ChoiceField):
                description += str(dict(getattr(v, 'choices', {})))
            if getattr(v, 'required', True) is not False:
                required.append(k)
            typ = serializer_field_mapping.get(type(v), openapi.TYPE_STRING)
            dit[k] = openapi.Schema(description=description, type=typ)
        return dit, required
    else:
        for k, v in fields.items():
            description = getattr(v, 'label', '')
            if isinstance(v, ChoiceField):
                description += str(dict(getattr(v, 'choices', {})))
            elif isinstance(v, serializers.SerializerMethodField):
                continue
            typ = serializer_field_mapping.get(type(v), openapi.TYPE_STRING)
            dit[k] = openapi.Schema(description=description, type=typ)

        return dit


class ViewSwagger(object):
    """
    openapi视图类
    重写请求参数和返回参数，调用对应的类方法即可
    """

    get_operation = '获取数据'
    get_req_params = []
    get_req_body = None
    get_res_data = None
    get_res_examples = {'json': {}}
    get_res_description = ' '
    get_res_code = 200

    post_operation = '新增数据'
    post_req_params = []
    post_req_body = None
    post_res_data = None
    post_res_examples = {'json': {}}
    post_res_description = ' '
    post_res_code = 200

    put_operation = '修改数据'
    put_req_params = []
    put_req_body = None
    put_res_data = None
    put_res_examples = {'json': {}}
    put_res_description = ' '
    put_res_code = 200

    delete_operation = '删除数据'
    delete_req_params = []
    delete_req_body = None
    delete_res_data = None
    delete_res_examples = {'json': {}}
    delete_res_description = ' '
    delete_res_code = 200

    @classmethod
    def req_serialize_schema(cls, serializer):
        return serializer_to_swagger(serializer, get_req=True)

    @classmethod
    def res_serialize_schema(cls, serializer):
        return serializer_to_swagger(serializer, get_req=False)

    @classmethod
    def get(cls):
        ret = {
            'manual_parameters': cls.get_req_params,
            'request_body': cls.get_req_body,
            'operation_summary': cls.get_operation,
            'responses': {
                cls.get_res_code: openapi.Response(description=cls.get_res_description, schema=cls.get_res_data,
                                                   examples=cls.get_res_examples)}
        }
        return ret

    @classmethod
    def post(cls):
        ret = {
            'manual_parameters': cls.post_req_params,
            'request_body': cls.post_req_body,
            'operation_summary': cls.post_operation,
            'responses': {
                cls.post_res_code: openapi.Response(description=cls.post_res_description, schema=cls.post_res_data,
                                                    examples=cls.post_res_examples)}
        }
        return ret

    @classmethod
    def put(cls):
        ret = {
            'manual_parameters': cls.put_req_params,
            'request_body': cls.put_req_body,
            'operation_summary': cls.put_operation,
            'responses': {
                cls.put_res_code: openapi.Response(description=cls.put_res_description, schema=cls.put_res_data,
                                                   examples=cls.put_res_examples)}
        }
        return ret

    @classmethod
    def delete(cls):
        ret = {
            'manual_parameters': cls.delete_req_params,
            'request_body': cls.delete_req_body,
            'operation_summary': cls.delete_operation,
            'responses': {
                cls.delete_res_code: openapi.Response(description=cls.delete_res_description,
                                                      schema=cls.delete_res_data,
                                                      examples=cls.delete_res_examples)}
        }
        return ret

　　下面只要在视图中单独定义对应的字段即可，gender.py 如下

import copy

from django.utils.decorators import method_decorator

from ani import models
from ani.serializer import GenderSerializer
from utils.decorators import request_decrypt, auth_token
from utils.myView import MyPagination, MyView, MixinGetList, MixinPostCreateModel, MixinPutUpdateModel, \
    MixinDeleteDestroyModel

from drf_yasg import openapi
from drf_yasg.utils import swagger_auto_schema
from utils.util import ViewSwagger


class APISwagger(ViewSwagger):
    serializer = GenderSerializer
    res_ser_schema = ViewSwagger.res_serialize_schema(serializer)
    req_ser_schema, req_ser_required_fields = ViewSwagger.req_serialize_schema(serializer)
    get_operation = '获取数据'
    get_req_params = [
        openapi.Parameter(name='name__icontains', in_=openapi.IN_QUERY, description='过滤包含该字段', type=openapi.TYPE_STRING,
                          required=False),
    ]
    get_req_body = None
    get_res_data = openapi.Schema(type=openapi.TYPE_OBJECT, properties={
            'data': openapi.Schema(description='', type=openapi.TYPE_ARRAY, items=openapi.Schema(type=openapi.TYPE_OBJECT, properties={
                **res_ser_schema
            })),
            'total': openapi.Schema(description='总数', type=openapi.TYPE_INTEGER),
        })
    get_res_examples = {'json': {}}
    get_res_description = 'get返回'
    get_res_code = 200

    post_schema = copy.copy(req_ser_schema)
    del post_schema['id']
    post_operation = '新增数据'
    post_req_params = []
    post_req_body = openapi.Schema(
            type=openapi.TYPE_OBJECT,
            properties={
                **post_schema
                },
            required=req_ser_required_fields
        )
    post_res_data = openapi.Schema(type=openapi.TYPE_OBJECT, properties={
                **res_ser_schema
        })
    post_res_examples = {'json': {}}
    post_res_description = ' '
    post_res_code = 200

    put_fields = req_ser_required_fields
    put_fields.append('id')
    put_operation = '新增数据'
    put_req_params = []
    put_req_body = openapi.Schema(
        type=openapi.TYPE_OBJECT,
        properties={
            **req_ser_schema
        },
        required=put_fields
    )
    put_res_data = openapi.Schema(type=openapi.TYPE_OBJECT, properties={
        **res_ser_schema
    })
    put_res_examples = {'json': {}}
    put_res_description = ' '
    put_res_code = 200


@method_decorator([swagger_auto_schema(**APISwagger.delete())], name='delete')
@method_decorator([swagger_auto_schema(**APISwagger.put())], name='put')
@method_decorator([swagger_auto_schema(**APISwagger.post())], name='post')
@method_decorator([swagger_auto_schema(**APISwagger.get())], name='get')
# @method_decorator(auth_token, name='get')
class GenderView(MyView, MixinGetList, MixinPostCreateModel, MixinPutUpdateModel, MixinDeleteDestroyModel):
    """
    get:
        查询
    post:
        新增
    put:
        修改
    delete:
        删除

    """
    queryset = models.Gender.objects.all()
    serializer_class = GenderSerializer
    all_serializer_class = GenderSerializer
    filter_class = ['name__icontains']
    pagination_class = MyPagination
    lookup_field = 'id'
    ordeing_field = ('-id',)

　　打开的接口文档变成

　　try it out 调用接口，得到一样的数据

　　注意：如果是post请求提交表单数据的时候，那么这个视图只能解析  parser_classes = [MultiPartParser]，自定义的字段和get请求差不多，只需要将 _in=openapi.IN_FORM  即可

　　项目文件结构