如何在Django 1.11版本的Django REST Swagger中填写响应schema

第一步：确认版本适配 #

Django 1.11 最高兼容的 django-rest-swagger 版本为 2.2.0，先确认版本匹配，不匹配执行以下命令安装：
pip install django-rest-swagger==2.2.0

第二步：基础配置 #

在项目settings.py中补充以下配置：

• 在INSTALLED_APPS列表中加入rest_framework_swagger
• 补充REST框架和Swagger全局配置：

REST_FRAMEWORK = {
    'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.coreapi.AutoSchema',
    # 其余原有配置保持不变
}

SWAGGER_SETTINGS = {
    # 开启注释解析
    'ENABLE_YAML_DOCSTRING': True,
    'SHOW_RESPONSE_HEADERS': True,
    # 其余配置按需配置即可
}

第三步：视图层配置（两种方式可选） #

方式1：通过docstring原生配置（无需额外依赖） #

直接在视图的文档字符串中按照YAML格式定义响应结构，示例：

from rest_framework.views import APIView
from rest_framework.response import Response
from .serializers import YourResponseSerializer

class YourDataView(APIView):
    """
    get:
    接口功能描述：获取指定数据列表
    ---
    # 响应结构定义
    responses:
        200:
            description: 请求成功
            schema:
                $ref: '#/definitions/YourResponseSerializer'
        400:
            description: 请求参数错误
        404:
            description: 资源不存在
    """
    def get(self, request):
        # 你的业务逻辑
        data = YourModel.objects.all()
        ser = YourResponseSerializer(data, many=True)
        return Response(ser.data)

如果不想关联Serializer，也可以直接在docstring里写字段定义：

"""
    get:
    接口功能描述
    ---
    responses:
        200:
            description: 成功
            schema:
                type: object
                properties:
                    code:
                        type: integer
                        description: 状态码，200为成功
                    msg:
                        type: string
                        description: 状态描述
                    data:
                        type: array
                        items:
                            type: object
                            properties:
                                id:
                                    type: integer
                                    description: 数据ID
                                name:
                                    type: string
                                    description: 数据名称
    """

方式2：通过装饰器配置（需要安装适配版本的drf-yasg） #

如果偏好装饰器写法，可安装适配Django1.11的drf-yasg版本：
pip install drf-yasg==1.17.1
之后在视图上添加装饰器绑定响应结构即可：

from rest_framework import generics
from drf_yasg.utils import swagger_auto_schema
from .serializers import YourResponseSerializer

class YourDataView(generics.ListAPIView):
    serializer_class = YourResponseSerializer
    
    @swagger_auto_schema(
        operation_description="接口功能描述",
        responses={
            200: YourResponseSerializer(many=True),
            400: "参数错误"
        }
    )
    def get(self, request, *args, **kwargs):
        return super().get(request, *args, **kwargs)

注意事项 #

• Serializer类需要明确定义所有字段的类型、verbose_name或help_text，这些信息会自动被解析到Schema中
• 配置完成后需要重启Django服务，清除浏览器缓存后再刷新Swagger页面
• 如果使用函数视图，docstring或者装饰器的写法逻辑和类视图一致，只需对应请求方法配置即可

内容的提问来源于stack exchange，提问作者Павел Иванов