Django REST Framework + drf-yasg: Django REST Framework 文档生成

drf-yasg —— Django REST Framework 文档生成
drf-yasg 安装及全局配置
安装以及这个官方文档非常详细的描述了，我就不多说了。

配置好并运行 Django 项目以后，就可以使用浏览器访问 /swagger/ 和 /redoc/ （链接取决于你的 urls 的配置）看到两种风格的文档了。我个人比较喜欢 Swagger 的，所以下面均用 Swagger 文档的界面作截图。
在 Parameters 和 Response 的地方默认展示 Example Value 而不是 Model，所以各位可以在 <project_name>/settings.py 中添加下面几行：

SWAGGER_SETTINGS = {
    'DEFAULT_MODEL_RENDERING': 'example'
}

Swagger 的方法是使用 drf_yasg.utils.swagger_auto_schema 作为装饰器修饰每个视图。

可以装饰 Django 风格的 View：
A Parameter of TYPE_ARRAY需要items密钥：

param1 = openapi.Parameter('param_name',
                            in_=openapi.IN_QUERY,
                            description='description of param',
                            type=openapi.TYPE_ARRAY,
                            items=openapi.Items(type=openapi.TYPE_STRING)  # <------
                            required=True
)

from drf_yasg.utils import swagger_auto_schema

@swagger_auto_schema(
    method='POST',
    operation_summary='注册新用户',
    operation_description='成功返回 201\n'
                          '失败（参数错误或不符合要求）返回 400',
    request_body=openapi.Schema(type=openapi.TYPE_OBJECT, properties={
        "email": openapi.Schema(type=openapi.TYPE_STRING, format=openapi.FORMAT_EMAIL, description='邮箱'),
        "password": openapi.Schema(type=openapi.TYPE_STRING, description='密码'),
    }),
    responses={200: Schema_None}
)
@api_view(['POST'])
def signup(request: WSGIRequest) -> Response:
    register_serializer = UserRegisterSerializer(data=request.data)
    if register_serializer.is_valid():
        u = register_serializer.save()
        user_serializer = UserSerializer(u)
        return Response(user_serializer.data, status=status.HTTP_201_CREATED)
    return Response(register_serializer.errors, status=status.HTTP_400_BAD_REQUEST)

也可以对 APIView 的 post get 等函数进行装饰：

class ActivityCheckInView(APIView):
    @swagger_auto_schema(
        operation_summary='用户签到',
        operation_description='可能会有以下情况：\n'
                              '1. 签到成功，用户经验+10，每位管理员经验+50，返回 200\n'
                              '2. 活动不存在，返回 404\n'
                              '3. POST 数据不包含签到码，返回 400\n'
                              '4. 演讲者关闭了签到，返回 403\n'
                              '5. 签到码错误，返回 403\n'
                              '注：要求登录，否则返回 403',
        request_body=Schema_object(Schema_check_in_code),
        responses={201: None, 403: Schema_object(Schema_detail)}
    )
    def post(self, request: WSGIRequest, id: int) -> Response:
        if not Activity.objects.filter(id=id):
            return Response({"detail": "活动不存在"}, status=status.HTTP_404_NOT_FOUND)
        activity = Activity.objects.get(id=id)
        if "check_in_code" not in request.POST:
            return Response({"detail": "POST 数据不包含签到码"}, status=status.HTTP_400_BAD_REQUEST)
        if activity.datetime.date() != datetime.now().date():
            return Response({"detail": "非当日活动"}, status=status.HTTP_403_FORBIDDEN)
        if not activity.check_in_open:
            return Response({"detail": "演讲者已关闭签到"}, status=status.HTTP_403_FORBIDDEN)
        if request.POST["check_in_code"] != activity.check_in_code:
            return Response({"detail": "签到码错误"}, status=status.HTTP_403_FORBIDDEN)

        activity.attender.add(request.user)

        return Response(status=status.HTTP_200_OK)

还可以对 GeneticAPIView 进行装饰：

from django.utils.decorators import method_decorator

@method_decorator(name="get", decorator=swagger_auto_schema(
        operation_summary='获取沙龙信息',
        operation_description='获取沙龙信息\n'
                              '注：需要登录',
))
@method_decorator(name="put", decorator=swagger_auto_schema(
    operation_summary='更新沙龙信息',
    operation_description='应答和 PATCH 方法相同，但 PUT 要求在请求中提交所有信息，不推荐使用',
))
@method_decorator(name="patch", decorator=swagger_auto_schema(
    operation_summary='更新沙龙部分信息',
    operation_description='更新沙龙信息，成功返回 200\n'
                          '如沙龙不存在，返回 404\n'
                          '如更新值不合法，返回 400\n'
                          '注：更新参与者名单请使用 `/users/check_in/` 或 `/users/check_in_admin/` 接口\n'
                          '注：需要是沙龙演讲者或管理员，否则返回 403\n'
                          '注：PATCH 方法可以只提交更新的值，也可以提交所有值',
))
@method_decorator(name="delete", decorator=swagger_auto_schema(
    operation_summary='删除沙龙',
    operation_description='删除沙龙，成功返回 204\n'
                          '注：需要是沙龙演讲者或管理员，否则返回 403',
))
class ActivityDetailView(RetrieveUpdateDestroyAPIView):
    permission_classes = (IsAuthenticated, IsPresenterOrAdminOrReadOnly, )
    queryset = Activity.objects.all()
    serializer_class = ActivitySerializer

对于 GeneticAPIView，Swagger 能够自动捕获其 Serializer 以及 ModelSerializer 并作为参数！除此之外，它还可以正确识别各 Serializer 类中的read_only_fields，并在请求的 Parameters 中去掉！
当然，对于 APIView 和 Django View，也是可以在 swagger_auto_schema 手动设置参数、返回值的。而如果对 GeneticAPIView 设置后，就会覆盖原来的设置。
对于 POST、PATCH 的放在 request_body 里的数据格式，可以放在 request_body 的参数部分，这个参数可以接收 rest_framework.Serializer 双厨狂喜，或是 openapi.Schema。
response 的参数也是类似，只是变成了一个 dict，因为每种 response body 应当对应一个 HTTP 状态码。
文档中提到，如果 responses 参数中没有 2xx 类的，会自动添加一个 200（对于 GET PUT PATCH），或是 201 （对于 POST）或 204（对于 DELETE）。要想屏蔽这个 2xx，只需要添加 {200: None}。

这个 None 有用，但是并不能通过 Pycharm 的类型检测（强迫症震怒）：

作为强迫症，可以定义一个 Schema_none = None，然后：

绕开 Pycharm 的类型检测

django doesn’t declare an explicit app_label and isn’t in an application in INSTALLED_APPS.

name=‘模块名的路径’

GenericAPIView与APIView 作为两大继承视图的区别
GenericViewSet和ViewSet都继承了ViewSetMixin，as_view都可以配置 请求-函数 映射
GenericViewSet继承的是GenericAPIView视图类，用来完成标准的model类操作接口
ViewSet继承的是APIView视图类，用来完成不需要model类参与，或是非标准的model类操作接口post请求在标准的model类操作下就是新增接口，登陆的post不满足post请求验证码接口，不需要model类的参与

drf视图基类，视图扩展类和视图子类

permission_classes 提供的权限django_drf

Django DRF 认证、权限、频率
自定义权限类和自定义认证类

自定义批量删除


Django中那些令人蒙圈的概念