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
相关产品推荐
相关产品推荐

