drf-yasg 模块细节性说明（自定义请求体，自定义响应体，自定义响应Content-Type, 自定义文档接口标题）

1.模块安装

pip install drf-yasg

2.模块配置

• settings.py中写入以下配置：

SWAGGER_SETTINGS = {
    'PERSIST_AUTH': True,
    'REFETCH_SCHEMA_WITH_AUTH': True,
    'REFETCH_SCHEMA_ON_LOGOUT': True,

    'SECURITY_DEFINITIONS': {
        'JWT': {
            'type': 'apiKey',
            'name': 'Authorization',
            'in': 'header'
        },
    }
}

• 主路由 urls.py 中写入一下配置：

from django.conf.urls import url
from rest_framework import permissions

from drf_yasg import openapi
from drf_yasg.views import get_schema_view

from utils.login import LoginObtainJSONWebToken

SchemaView = get_schema_view(
    openapi.Info(
        title="XXXXX服务平台",
        default_version='v1.0',
        description="""
            XXXXX平台 API 遵循 REST 标准进行设计。
            我们的 API 是 可预期的 以及 面向资源 的，接受 `form-encoded` 请求正文，返回 `JSON-encoded` 响应， 使用标准的 HTTP 响应代码 ，认证（JWT）和参数。
            所有请求和响应的编码均为 UTF-8。
        """,
        contact=openapi.Contact(email="1182900548@qq.com"),
        license=openapi.License(name="BSD License"),
    ),
    public=True,
    # schema view本身的权限类
    permission_classes=(permissions.AllowAny,),
)

urlpatterns = [
    url(r'^swagger(?P<format>.json|.yaml)$', SchemaView.without_ui(cache_timeout=0), name='schema-json'),  # 导出
    url(r'^redoc/$', SchemaView.with_ui('redoc', cache_timeout=0), name='schema-redoc'),  # redoc美化UI
    url(r'^swagger/$', SchemaView.with_ui('swagger', cache_timeout=None), name='cschema-swagger-ui'),
]

3.文档生成

(1) 接口描述，接口分组，搜索参数，接口标题设置

class UserAdminViewSet(ModelViewset):

    queryset = models.UsersModel.objects.all()

    def get_serializer_class(self):
        return serializers.UserAdminSerializersForChange

    @swagger_auto_schema(
    	# 接口描述，支持markdown语法
        operation_description=""" 用户列表""",
        # 接口参数 GET请求参数
        manual_parameters=[
            # 声明参数
            openapi.Parameter(
                #参数名称
	            "name", 
	            # 参数类型为query
	            openapi.IN_QUERY, 
	            # 参数描述
	            description="用户名称模糊搜索", 
	            # 参数字符类型
	            type=openapi.TYPE_STRING
            ),
        ],
        # 接口标题
        operation_summary='用户列表', 
        # 接口所属分组，会单独将接口拆出来放到 用户管理 分组中
        tags=['用户管理']
    )
    def list(self, request, *args, **kwargs):
        return super(UserAdminViewSet, self).list(request, *args, **kwargs)

（2）POST请求数据提交自定义提交表单

• 方式1，使用描述性序列化器

class ConfigModelSerializers(serializers.ModelSerializer):
    # 接口文档描述序列化器
    # help_text 可以自定义字段描述信息
    # require = True 可以指定该参数是否必传
    item = serializers.IntegerField(help_text='配置项的Key', required=True)

    class Meta:
        model = models.ConfigModel
        fields = ('item', 'context')

class ConfigView(APIView):
    """配置表更新和查询接口"""

    @swagger_auto_schema(
        operation_description="修改配置信息",
        # 返回的数据，对应的状态码可以指定一个自定义的序列化器指定返回结果
        responses={404: 'Not found', 200: ConfigModelSerializers},
        # APIView不会自动生成请求体，可以指定一个描述用的序列化器
        request_body=serializers.ConfigModelSerializers,
        tags=['配置信息'],
        operation_summary='配置信息修改',
    )
    def put(self, request):
        return Response(status.HTTP_200_OK)

• 也可以不使用序列化器自定义构造请求体

# 若有方法没有被重写，可以给类加装饰器给相应请求方法添加描述
@method_decorator(name='retrieve', decorator=swagger_auto_schema(
    operation_description="基本信息", operation_summary='基本信息', tags=['单条差看']
))
@method_decorator(name='update', decorator=swagger_auto_schema(
    operation_description="数据更新", operation_summary='数据更新', tags=['更新']
))
class UsersViewSet(ModelViewSet):
    queryset = models.UsersModel.objects.all()
    def get_serializer_class(self):
        return serializers.UserSerializersForChange

    @decorators.action(methods=['put'], detail=True)
    @swagger_auto_schema(
        operation_description="修改密码",
        operation_summary='修改密码',
        # 也可以自定义返回的 响应体数据 
        # openapi.Response(description='响应描述',examples={'响应数据的content-Type':'响应数据'}) 
        responses={400: '原密码错误', 200: openapi.Response(description='ok', examples={
            'application/json': {'messgage': '密码修改成功！'}
        })},
        request_body=openapi.Schema(
            # 构造的请求体为 dict 类型
            type=openapi.TYPE_OBJECT,
            # 构造的请求体中 必填参数 列表
            required=['password', 'new_password'],
            # 自定义请求体 ， key为请求参数名称，值为参数描述
            properties={
                'password': openapi.Schema(type=openapi.TYPE_STRING,required=True, description='原密码'),
                'new_password': openapi.Schema(type=openapi.TYPE_STRING, description='新密码')
            }
        ),
        tags=['密码修改']
    )
    def change_pwd(self, *args, **kwargs):
        """修改密码"""
        return self.error('密码必须在8-12位之间!')