drf-spectacular技术咨询：自定义Schema及添加独立模型至Schema

1. 创建自定义Schema并覆盖API端点的Schema #

有两种常用方式实现，根据需求选择即可：

方式一：自定义Serializer + @extend_schema装饰器 #

先定义对应自定义Schema的Serializer类，再在视图上通过装饰器指定覆盖请求/响应Schema：

from rest_framework import serializers, views
from drf_spectacular.utils import extend_schema

# 定义自定义Schema对应的Serializer
class CustomUserSchema(serializers.Serializer):
    id = serializers.IntegerField()
    username = serializers.CharField(max_length=100)
    custom_status = serializers.BooleanField(help_text="自定义状态字段")

# 在视图中覆盖端点默认Schema
class UserManageView(views.APIView):
    @extend_schema(
        request=CustomUserSchema,  # 覆盖请求体Schema
        responses=CustomUserSchema,  # 覆盖响应体Schema
        description="自定义用户信息操作端点"
    )
    def post(self, request):
        # 视图业务逻辑
        return Response({"status": "success"})

方式二：用inline_serializer直接在装饰器中定义 #

如果不需要复用Schema，可直接在装饰器内用inline_serializer定义临时自定义Schema，无需单独写Serializer类：

from rest_framework import views, serializers
from drf_spectacular.utils import extend_schema, inline_serializer

class UserManageView(views.APIView):
    @extend_schema(
        request=inline_serializer(
            name="CustomUserRequestSchema",
            fields={
                'username': serializers.CharField(max_length=100),
                'email': serializers.EmailField(),
                'age': serializers.IntegerField(min_value=18)
            }
        ),
        responses=inline_serializer(
            name="CustomUserResponseSchema",
            fields={
                'user_id': serializers.IntegerField(),
                'message': serializers.CharField()
            }
        )
    )
    def post(self, request):
        # 视图业务逻辑
        return Response({"user_id": 1, "message": "创建成功"})

代码放置说明 #

以上代码直接放在对应视图文件中，和视图类/函数放在一起即可，drf-spectacular会自动扫描识别。如果是视图集，可使用@extend_schema_view为不同动作单独指定Schema。

2. 将自定义模型添加到Schema中，但不关联任何API端点 #

要让未绑定端点的模型/Schema出现在文档里，可通过以下两种方式实现：

方式一：用register_serializer注册自定义Serializer #

在项目的urls.py或专门的Schema配置文件中，直接注册目标Serializer，drf-spectacular会将其加入Schema的components列表：

from drf_spectacular.utils import register_serializer
from rest_framework import serializers

# 定义未关联端点的自定义Serializer
class StandaloneModelSchema(serializers.Serializer):
    model_id = serializers.IntegerField()
    model_name = serializers.CharField(max_length=200)
    extra_data = serializers.JSONField(help_text="额外扩展字段")

# 注册该Serializer，使其出现在Schema文档中
register_serializer(StandaloneModelSchema)

方式二：空视图 + @extend_schema装饰 #

创建一个不对外暴露的空视图，通过装饰器指定要展示的Schema，并设置exclude=True避免视图出现在端点列表中：

from rest_framework.views import APIView
from drf_spectacular.utils import extend_schema, inline_serializer

class UnattachedSchemaView(APIView):
    @extend_schema(
        responses=inline_serializer(
            name="StandaloneCustomSchema",
            fields={
                'key': serializers.CharField(),
                'value': serializers.FloatField(),
                'metadata': serializers.DictField()
            }
        ),
        exclude=True  # 隐藏视图端点，但保留Schema
    )
    def get(self, request):
        # 无需实际业务逻辑，仅用于注册Schema
        pass

代码放置说明 #

• register_serializer代码可放在项目根目录的schema.py或urls.py顶部，确保项目启动时能被加载。
• 空视图方式可放在任意视图文件中，只要属于INSTALLED_APPS下的模块，drf-spectacular扫描器就能识别到。

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