如何使用drf-yasg为Django REST Framework接口生成OpenAPI文档？

问题原因 #

drf-yasg默认无法自动识别基础APIView的参数、响应结构，你的代码还存在几个导致识别失败的小错误，按以下步骤调整即可：

调整步骤 #

1. 修正属性名与基类错误 #

• 视图中serializer_classes是错误写法，正确属性名是serializer_class，且不需要用列表包裹，直接赋值序列化器类即可
• 把视图基类从APIView替换为GenericAPIView，该基类的serializer_class属性会被drf-yasg自动识别，同时可以复用序列化器的参数校验能力

2. 统一字段命名 #

你当前序列化器中定义的时间字段是passage_at，但视图中实际读取的是visit_at，二者需要保持一致，这里我们统一修改为visit_at。

3. 调整post方法逻辑，复用序列化器校验 #

不需要手动解析日期参数，序列化器的DateTimeField会自动完成格式校验与类型转换，同时drf-yasg会自动读取序列化器的字段规则生成请求参数文档。

4. （可选）指定响应结构 #

如果需要让Swagger展示响应的结构规范，可以额外定义响应序列化器，或者通过drf-yasg的装饰器手动指定响应格式。

调整后完整代码示例 #

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

# 序列化器字段和视图读取字段保持一致
class HasMilkSerializer(serializers.Serializer):
    store = serializers.CharField(min_length=6, max_length=6)
    visit_at = serializers.DateTimeField()

# 可选：定义响应序列化器，让响应结构也自动生成文档
class HasMilkResponseSerializer(serializers.Serializer):
    store = serializers.CharField(min_length=6, max_length=6)
    has_milk = serializers.BooleanField()

class HasMilkView(CsrfExemptMixin, GenericAPIView):
    http_method_names = ['post']
    authentication_classes = [BasicAuthWithKeys]
    # 修正属性名，不需要列表包裹
    serializer_class = HasMilkSerializer

    # 手动指定响应序列化器
    @swagger_auto_schema(responses={200: HasMilkResponseSerializer()})
    def post(self, request):
        # 用序列化器做参数校验，不需要手动解析日期
        serializer = self.get_serializer(data=request.data)
        serializer.is_valid(raise_exception=True)
        store = serializer.validated_data['store']
        visit_at = serializer.validated_data['visit_at']
        return Response({'store': store, 'has_milk': has_milk(store, visit_at)})

无需修改基类的备选方案 #

如果你不想把基类换成GenericAPIView，只需要给post方法添加@swagger_auto_schema装饰器手动指定请求体即可：

class HasMilkView(CsrfExemptMixin, APIView):
    http_method_names = ['post']
    authentication_classes = [BasicAuthWithKeys]

    @swagger_auto_schema(request_body=HasMilkSerializer, responses={200: HasMilkResponseSerializer()})
    def post(self, request):
        # 原有逻辑
        ...

内容的提问来源于stack exchange，提问作者kramer65