You need to enable JavaScript to run this app. drf-yasg如何隐藏自动生成Schema字段或显式定义Schema
优惠活动
大模型
产品
解决方案
定价
更多

drf-yasg如何隐藏自动生成Schema字段或显式定义Schema

操作方案

先明确两个核心问题

  • read_only/write_only的字段过滤逻辑需要手动开启全局开关才能生效,不是默认行为
  • 直接在装饰器里塞裸字典定义Schema的写法不被drf-yasg支持,会直接触发500错误
  • 完全不需要为了调整文档展示单独写一套重复的序列化器,框架内置功能就能覆盖所有需求

方案1:开全局自动拆分(零侵入,优先推荐)

这是框架原生设计的能力,不需要改动任何业务序列化器或者视图代码。
在项目配置的SWAGGER_SETTINGS节点加一行配置:

SWAGGER_SETTINGS = {
    # 原有已配置的参数全部保留
    "COMPONENT_SPLIT_REQUEST": True
}

配置重启后自动生效的效果:

  • 请求体Schema会自动过滤所有read_only=True的字段,只列实际需要客户端传的参数
  • 响应体Schema会自动过滤所有write_only=True的字段,只列实际返回给客户端的内容
  • 嵌套序列化器的字段会同步执行过滤,比如你在TokensSerializer里设为write_only的username字段,不会出现在响应文档的必填项里,解决之前Tokens Schema要求传username的问题

方案2:单视图局部隐藏字段(适合不想改全局配置的场景)

不想动全局配置的话,不需要手写完整Schema,直接用装饰器的exclude_fields参数列要隐藏的字段就行。

  • 嵌套字段支持用双下划线写路径,比如要隐藏嵌套在tokens下的username字段,直接写路径即可
  • 代码示例:
from drf_yasg.utils import swagger_auto_schema

class LoginView(GenericAPIView):
    serializer_class = LoginSerializer

    @swagger_auto_schema(
        responses={200: LoginSerializer()},
        # 这里直接列需要从生成的文档里剔除的字段,不影响序列化器实际运行
        exclude_fields=["password", "tokens__username"]
    )
    def post(self, request):
        # 原有业务逻辑完全不用改
        pass

这种方式生成的Schema完全基于现有序列化器的定义,只会删掉你指定的字段,没有额外的代码维护成本。

方案3:完全自定义响应Schema(修复之前的500报错)

之前自定义Schema报500的核心原因是直接传了裸字典作为schema值,框架解析器拿到字典后无法按OpenAPI结构校验,直接抛服务端错误。必须用框架提供的构造类来定义结构,正确写法如下:

from drf_yasg import openapi

@swagger_auto_schema(
    responses={
        201: openapi.Response(
            description="登录成功后的返回内容",
            schema=openapi.Schema(
                type=openapi.TYPE_OBJECT,
                required=["username", "email", "tokens"],
                properties={
                    "username": openapi.Schema(
                        type=openapi.TYPE_STRING,
                        maxLength=64,
                    ),
                    "email": openapi.Schema(
                        type=openapi.TYPE_STRING,
                        maxLength=254,
                        readOnly=True
                    ),
                    "tokens": openapi.Schema(
                        ref="#/definitions/Tokens"
                    )
                }
            )
        )
    }
)

这种写法完全符合OpenAPI规范,不会触发解析错误。

内容的提问来源于stack exchange,提问作者Matt McCarthy

相关产品推荐
方舟 Agent Plan

超全模态模型 × Harness 升级,最新支持 Deepseek-V4.1-Flash、GLM-5.3 系列、Doubao-Seedream-5.0-pro、Kimi-K3 (部分), 限时 9.9 元起

最近更新时间:2026.10.27 17:36:04