无Serializer场景下如何用drf-spectacular定义Django API component schema

你之前的配置仅声明了响应为通用对象类型，未绑定具体自定义结构，因此Swagger中Component区域为空。按以下方式修改即可实现需求：

完整修改后代码 #

from rest_framework.decorators import api_view
from drf_spectacular.utils import extend_schema, OpenApiExample, OpenApiComponent
from drf_spectacular.types import OpenApiTypes
from rest_framework.response import Response

@extend_schema(
    examples=[OpenApiExample(
        value=[
            {'title': 'A title'},
            {'title': 'Another title'},
        ],
    )],
    responses={
       200: {
           "type": "array",
           "items": OpenApiComponent(
               name="Article",
               type="object",
               description="文章对象结构",
               properties={
                   "title": {"type": "string", "description": "文章标题"}
               },
               required=["title"]
           )
       }
    }
)
@api_view(['GET'])
def list_articles(request):
    return Response([{'title': 'Test1'}, {'title': 'Test2'}])

关键配置说明 #

• 新增导入OpenApiComponent工具类，专门用于手动声明OpenAPI组件
• OpenApiComponent的name参数对应Swagger中Components区域展示的组件名称，相同名称的组件会自动去重，可在多个接口中复用
• properties字段定义组件的字段结构，支持指定字段类型、描述、枚举值等属性
• required参数用于声明该组件的必填字段
• 示例接口返回数组结构，因此外层用"type": "array"，通过items关联自定义的Article组件即可；如果是返回单个对象，直接将OpenApiComponent实例赋值给响应状态码对应的value即可

配置完成后重新生成Schema，即可在Swagger的Components区域看到你定义的Article组件，对应接口的响应结构也会关联到该组件。

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