DRF Spectacular extend_schema加载YAML响应配置失效求助

自定义extend_schema_from_yaml装饰器，通过加载YAML文件配置drf-spectacular的extend_schema生成Swagger文档。operation_id、summary、description、tags均正常生效，但responses配置无效果。

现有代码 #

装饰器代码 #

def extend_schema_from_yaml(yaml_file_path, operation_id=None):
    def decorator(view_func):
        with open(yaml_file_path, "r") as file:
            schema = yaml.safe_load(file)

        summary = schema.get("summary", "")
        description = schema.get("description", "")
        responses = schema.get("responses", {})
        tags = schema.get("tags")

        extend_schema_kwargs = {
            "operation_id": operation_id,
            "summary": summary,
            "description": description,
            "responses": responses,
        }

        if tags:
            extend_schema_kwargs["tags"] = tags

        # Apply extend_schema to the view function
        return extend_schema(**extend_schema_kwargs)(view_func)

    return decorator

YAML配置文件 #

tags:
  - "Tag"
summary: "Summary"
description: "Description"
responses:
  "200":
    description: "Numbers"
    content:
      application/json:
        schema:
          type: array
          items:
            type: integer
          example: [2020, 2021, 2022]

问题原因 #

drf-spectacular的extend_schema对responses参数的类型有要求：它需要接收OpenApiResponse实例、序列化器类/实例，或者能被内部解析的特定结构字典。直接传递YAML加载的原生字典，无法被框架正确识别转换为Swagger响应定义。

解决方案 #

修改装饰器，将YAML中加载的responses字典转换为OpenApiResponse对象的结构，确保框架能正确解析。

修改后的装饰器代码 #

from drf_spectacular.utils import extend_schema, OpenApiResponse
import yaml

def extend_schema_from_yaml(yaml_file_path, operation_id=None):
    def decorator(view_func):
        with open(yaml_file_path, "r") as file:
            schema = yaml.safe_load(file)

        summary = schema.get("summary", "")
        description = schema.get("description", "")
        raw_responses = schema.get("responses", {})
        tags = schema.get("tags")

        # 将原生字典响应转换为OpenApiResponse实例
        responses = {}
        for status_code, resp_details in raw_responses.items():
            responses[status_code] = OpenApiResponse(
                description=resp_details["description"],
                content=resp_details.get("content", {})
            )

        extend_schema_kwargs = {
            "operation_id": operation_id,
            "summary": summary,
            "description": description,
            "responses": responses,
        }

        if tags:
            extend_schema_kwargs["tags"] = tags

        return extend_schema(**extend_schema_kwargs)(view_func)

    return decorator

说明 #

• 导入OpenApiResponse类，用它来包裹每个状态码的响应配置，明确告诉drf-spectacular这是一个标准的响应定义。
• 遍历YAML加载的responses字典，为每个状态码创建对应的OpenApiResponse实例，保留原有的description和content配置。
• 修改后，responses配置会被正确解析并生成到Swagger文档中。

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