如何在drf-spectacular中配置展示400校验错误响应详情？

你使用drf-spectacular生成接口文档的场景下，完全可以实现自动从序列化器提取校验错误信息填充到400响应说明中，无需手动拼接错误内容。

具体修改步骤 #

1. 调整接口装饰器配置 #

首先确认你已经在extend_schema中指定了请求对应的序列化器，工具会自动扫描该序列化器的所有字段校验规则（必填、格式限制、数值范围等），关联生成400响应的错误结构：

from drf_spectacular.utils import extend_schema, OpenApiResponse, OpenApiExample
# 导入drf-spectacular内置的校验错误响应结构，不同版本路径可能略有差异，可根据实际版本调整
from drf_spectacular.serializers import ValidationErrorSerializer
# 导入你自己的业务请求序列化器
from .serializers import TransactionCreateSerializer

@extend_schema(
    summary="创建新交易",
    # 必须指定请求序列化器，才能自动关联字段的校验规则
    request=TransactionCreateSerializer,
    responses={
        201: OpenApiResponse(
            description='创建成功',
        ),
        400: OpenApiResponse(
            # 指定校验错误的响应结构
            response=ValidationErrorSerializer,
            description='请求参数错误，返回字段对应的校验错误详情',
            # 可选：自定义展示具体错误示例，会直接显示在文档的400响应区块
            examples=[
                OpenApiExample(
                    '必填字段缺失示例',
                    value={
                        "organisation_id": [
                            "该字段为必填项。"
                        ]
                    },
                    status_codes=[400]
                ),
                OpenApiExample(
                    '字段值无效示例',
                    value={
                        "amount": [
                            "金额必须大于0。"
                        ]
                    },
                    status_codes=[400]
                )
            ]
        ),
    },
)

2. 全局配置（可选） #

如果不想每个接口都重复配置400响应，可以在项目settings.py的SPECTACULAR_SETTINGS中添加全局默认响应配置，所有接口会自动带上400校验错误的说明：

SPECTACULAR_SETTINGS = {
    # 其余原有配置保持不变
    'DEFAULT_RESPONSES': [
        (400, 'drf_spectacular.serializers.ValidationErrorSerializer', '请求参数校验错误'),
    ]
}

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