如何在drf-spectacular生成的OpenAPI Schema中包含JSONField的JSON Schema定义？

方法一：全局字段扩展（推荐） #

通过自定义OpenApiSerializerExtension，自动识别带JSONSchemaValidator的JSONField，将验证器中的JSON Schema注入到OpenAPI Schema中，无需逐个修改序列化器。

1. 编写扩展类 #

创建一个扩展类，继承OpenApiSerializerExtension，针对JSONField做特殊处理：

from drf_spectacular.extensions import OpenApiSerializerExtension
from rest_framework.fields import JSONField
from django.core.validators import JSONSchemaValidator

class JSONSchemaValidatorJSONFieldExtension(OpenApiSerializerExtension):
    target_class = JSONField

    def map_serializer_field(self, auto_schema, direction):
        # 获取默认生成的schema
        base_schema = super().map_serializer_field(auto_schema, direction)
        # 遍历字段的验证器，找到JSONSchemaValidator
        for validator in self.target.validators:
            if isinstance(validator, JSONSchemaValidator):
                # 将自定义JSON Schema合并到基础schema中，保留nullable等原有属性
                custom_schema = validator.limit_value.copy()
                if 'nullable' in base_schema:
                    custom_schema['nullable'] = base_schema['nullable']
                if 'title' in base_schema:
                    custom_schema['title'] = base_schema['title']
                return custom_schema
        # 没有找到对应验证器时返回默认schema
        return base_schema

2. 注册扩展 #

在项目的settings.py中配置SPECTACULAR_SETTINGS，添加这个扩展：

SPECTACULAR_SETTINGS = {
    # 其他配置...
    'SERIALIZER_EXTENSIONS': [
        'your_app.path.to.extension.JSONSchemaValidatorJSONFieldExtension',
    ],
}

方法二：序列化器局部处理 #

如果只需要针对特定序列化器的字段生效，可以用@extend_schema_field直接指定JSON Schema：

from rest_framework import serializers
from drf_spectacular.utils import extend_schema_field
from .models import Car
from .schemas import my_schema  # 导入你的自定义JSON Schema

class CarSerializer(serializers.ModelSerializer):
    @extend_schema_field(my_schema)
    def data(self, obj):
        return obj.data

    class Meta:
        model = Car
        fields = ['name', 'data']

注意事项 #

• 确保你的my_schema符合OpenAPI 3.x规范，比如用nullable: true表示可空，而非JSON Schema的type: ["object", "null"]格式
• 如果自定义Schema中未指定title，会自动保留原字段的标题（如示例中的"Car Data"）

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