在drf-spectacular中自定义OpenAPI响应结构

概述

在使用drf-spectacular为Django REST框架生成OpenAPI/Swagger文档时，开发者经常需要自定义API响应结构。本文介绍如何通过extend_schema装饰器和OpenApiResponse类来实现这一需求。

基础响应自定义

最简单的响应自定义方式是直接指定序列化器：

@extend_schema(
    responses={
        status.HTTP_200_OK: LocationSerializer,
    }
)

这种方式适用于简单的响应场景，直接使用已定义的序列化器作为响应模型。

复杂响应结构

当需要更复杂的响应结构时，可以使用OpenApiResponse手动定义：

@extend_schema(
    responses={
        status.HTTP_404_NOT_FOUND: OpenApiResponse(
            description="资源不存在时的响应",
            response={
                "type": "object",
                "properties": {
                    "detail": {"type": "string", "example": "Not found."}
                },
            },
        ),
    }
)

这种方式允许开发者完全控制响应的结构和示例值。

结合序列化器的自定义响应

有时我们需要在自定义响应结构中嵌入序列化器的输出。例如，实现分页响应：

@extend_schema(
    responses=OpenApiResponse(
        inline_serializer(
            name="PagedResponse",
            fields={
                "count": serializers.IntegerField(),
                "results": LocationSerializer(many=True)
            }
        )
    )
)

这种模式可以生成类似如下的响应结构：

{
   "count": 100,
   "results": [...]
}

高级技巧

1. 多响应状态处理：可以同时定义多个HTTP状态码的响应
2. 复用响应结构：通过定义变量复用常见响应模式
3. 条件响应：根据请求参数返回不同结构

最佳实践

1. 保持响应结构一致性
2. 为每个响应提供清晰的描述
3. 使用示例值提高文档可读性
4. 考虑API版本兼容性

通过合理使用drf-spectacular提供的这些功能，开发者可以生成既准确又易于理解的API文档，大大提高API的可用性和开发效率。