drf_yasg @swagger_auto_schema POST请求文档不显示参数问题

问题根因 #

配置的EventSerializer存在两个核心问题导致yasg无法渲染请求参数：

1. 关联字段user、category全部设置为只读嵌套序列化器，yasg扫描后会判定序列化器没有可写入字段
2. 接口包含banner图片上传字段，但未指定接口接收multipart/form-data格式，yasg默认按JSON格式解析时会直接跳过文件字段，连带其他字段渲染异常
   另外装饰器顺序错误、未配置对应解析器也会触发同类问题。

修复步骤 #

• 调整序列化器读写逻辑
  外键字段不要全设为只读嵌套：user由后端从登录态获取，保持只读即可；category写入时接收分类ID，返回时嵌套展示分类详情；banner字段明确标注为图片上传字段。参考代码：

class EventSerializer(serializers.ModelSerializer):
    user = UserSerializer(read_only=True)
    # 写入时接收分类ID，映射到category外键
    category_id = serializers.PrimaryKeyRelatedField(
        queryset=EventCategory.objects.all(),
        write_only=True,
        source='category'
    )
    category = EventCategorySerializer(read_only=True)
    banner = serializers.ImageField(required=False, default='avatar.jpg')

    class Meta:
        model = Events
        fields = '__all__'

• 修正视图装饰器配置
  涉及文件上传必须指定请求格式为multipart/form-data，同时配置对应解析器，@swagger_auto_schema要放在更靠近视图函数的位置：

from drf_yasg.utils import swagger_auto_schema
from rest_framework.parsers import MultiPartParser, FormParser

@api_view(['POST'])
@permission_classes([IsAuthenticated])
@user_is_organization
@parser_classes([MultiPartParser, FormParser])
@swagger_auto_schema(
    operation_description="创建事件，仅组织类型账号可调用",
    request_body=EventSerializer,
    consumes=['multipart/form-data'],
    responses={200: EventSerializer()}
)
def registerEvent(request):
    """
    注册事件接口
    """
    # 替换原有手动取参逻辑，用序列化器做参数校验
    serializer = EventSerializer(data=request.data)
    serializer.is_valid(raise_exception=True)
    # 保存时自动绑定当前登录用户，不需要手动从request.data取user
    event = serializer.save(user=request.user)
    return Response(EventSerializer(event).data)

• 校验配置生效
  重启服务后强制刷新Swagger页面（清浏览器缓存），即可看到完整的请求参数输入项，包含图片上传控件和普通表单字段。

避坑提示 #

• 不要用无差别try:捕获所有异常，会吞掉参数校验、数据不存在等具体错误，既不利于调试，也会导致yasg无法生成正确的错误响应文档
• 只要接口包含文件上传字段，必须显式指定consumes=['multipart/form-data']和MultiPartParser解析器，否则yasg和接口本身都无法正确接收文件参数
• 嵌套序列化器默认不会被yasg识别为可写入字段，需要写入的外键字段单独用PrimaryKeyRelatedField或其他可写字段声明

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