drf-spectacular 如何为HTTP 204响应添加描述？现有配置未生效

原有写法的问题 #

• 直接写204: None仅能声明该状态码无返回体，既不会自动将你在全局examples中定义的204示例关联到对应响应块，也不会把示例内的描述同步为响应本身的说明文字
• 全局传入的examples如果没有和对应响应项做绑定，生成文档时会出现示例和响应状态码匹配错位的问题，最终导致自定义描述显示位置不对

正确配置方案 #

核心调整 #

不要将204响应的值设为None，改用OpenApiResponse类包装204响应：

• 直接在OpenApiResponse初始化参数中传入自定义的响应描述
• 将对应的204示例直接绑定到该响应对象下，不需要把204示例单独放在全局的examples数组中

可直接复用的代码示例 #

from drf_spectacular.utils import extend_schema, OpenApiResponse, OpenApiExample

@extend_schema(
    request=MyRequestSerializer,
    responses={
        200: MyResponseSerializer(many=True),
        204: OpenApiResponse(
            response=None,  # 明确声明204响应无返回体，避免生成多余的schema结构
            description="这里填写你的204自定义描述，比如：资源删除成功，接口无返回内容",
            examples=[
                OpenApiExample(
                    name="204成功响应示例",
                    status_codes=["204"],
                    value=None,
                    response_only=True
                )
            ]
        ),
    },
    # 其他状态码的示例可以正常保留在全局examples数组中
    examples=[
        # 其他非204状态码的示例...
    ]
)

补充说明 #

• 如果不需要给204响应配置可视化示例，仅需添加自定义描述，完全可以省略examples配置，只保留description参数即可生效
• OpenApiResponse的description参数内容会直接渲染到生成文档的204响应说明区域，和预期的自定义描述效果完全一致
• 不要把204的相关示例放到全局examples数组里，否则会出现示例无法正确关联到对应状态码的问题

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