如何用extend_schema_field为自定义字段配置请求响应差异化OpenAPI Schema

实现方案 #

drf_spectacular 的 @extend_schema_field 原生支持分别定义请求、响应两端的Schema结构，你不需要额外创建空序列化器，直接按如下方式配置即可：

首先导入依赖：

from drf_spectacular.types import OpenApiTypes
from drf_spectacular.utils import extend_schema_field, OpenApiObject

然后修改字段的装饰器配置：

@extend_schema_field(
    {
        "request": OpenApiTypes.BINARY,
        "response": OpenApiObject(
            properties={
                "image": OpenApiObject(
                    properties={
                        "url": OpenApiTypes.STR,
                        "name": OpenApiTypes.STR,
                    },
                    required=["url", "name"]
                ),
                "thumbnail": OpenApiObject(
                    properties={
                        "url": OpenApiTypes.STR,
                        "name": OpenApiTypes.STR,
                    },
                    required=["url", "name"],
                    nullable=True
                )
            },
            required=["image"]
        )
    }
)
class PictureSerializerField(ImageField):
    # 保留你原有字段的业务逻辑
    ...

如果你不想使用OpenApiObject语法，也可以直接写符合JSON Schema规范的字典，效果完全一致：

@extend_schema_field(
    {
        "request": OpenApiTypes.BINARY,
        "response": {
            "type": "object",
            "properties": {
                "image": {
                    "type": "object",
                    "properties": {
                        "url": {"type": "string"},
                        "name": {"type": "string"}
                    },
                    "required": ["url", "name"]
                },
                "thumbnail": {
                    "type": "object",
                    "properties": {
                        "url": {"type": "string"},
                        "name": {"type": "string"}
                    },
                    "required": ["url", "name"],
                    "nullable": True
                }
            },
            "required": ["image"]
        }
    }
)

配置完成后，Swagger文档会自动适配：请求参数显示为文件选择框，响应Schema渲染为你需要的嵌套字典结构。

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