如何使用DRF-Spectacular为单个Model或Serializer字段定义示例？

DRF-Spectacular 原生支持为单个 Model、Serializer 字段定义专属示例，实现逻辑与help_text自动生成字段描述的机制完全对齐，不需要为每个接口编写完整的请求/响应示例，常用实现方式有3种：

方式1：直接在Serializer字段声明时传入example参数 #

这是最通用的写法，和DRF原生字段参数完全兼容，DRF-Spectacular会自动提取参数值写入OpenAPI规范的对应字段节点，示例代码：

from rest_framework import serializers
from .models import User

class UserInfoSerializer(serializers.ModelSerializer):
    # 手动声明的字段直接加example参数即可
    phone = serializers.CharField(
        max_length=11,
        help_text="用户绑定手机号",
        example="13800138000" # 单字段示例定义位置和help_text完全一致
    )
    register_time = serializers.DateTimeField(
        read_only=True,
        example="2024-01-01T12:00:00Z"
    )

    class Meta:
        model = User
        fields = ["id", "phone", "register_time", "username"]

方式2：通过ModelSerializer的extra_kwargs给自动映射的字段加示例 #

如果使用ModelSerializer自动从Model映射字段、没有手动重写字段声明，可以直接在Meta类的extra_kwargs中给对应字段传example参数，和你平时配置help_text、write_only等参数的写法完全一致：

class UserInfoSerializer(serializers.ModelSerializer):
    class Meta:
        model = User
        fields = "__all__"
        extra_kwargs = {
            "id_card": {
                "help_text": "用户身份证号",
                "example": "110101199001011234" # 自动映射的id_card字段示例
            },
            "email": {
                "example": "zhangsan@example.com"
            }
        }

方式3：通过@extend_schema_field给复杂/动态字段加示例 #

如果是序列化器方法字段、第三方包提供的内置字段、需要动态生成示例的场景，可以用@extend_schema_field装饰器指定字段的schema配置，传入示例值：

from drf_spectacular.utils import extend_schema_field
from rest_framework import serializers
from .models import Order

class OrderSerializer(serializers.ModelSerializer):
    # 给自定义方法字段指定示例
    @extend_schema_field(
        serializers.CharField(help_text="订单编号", example="ORD-20240501-89757")
    )
    def get_order_sn(self, obj):
        return f"ORD-{obj.create_time.strftime('%Y%m%d')}-{obj.id}"

    class Meta:
        model = Order
        fields = "__all__"

规则说明 #

• 以上方式定义的单字段示例，会自动写入最终生成的openapi.yml对应字段的example属性，SwaggerUI、Redoc等文档工具会优先展示手动定义的示例，覆盖默认根据字段类型、正则规则自动生成的示例值
• 示例优先级遵循：视图级extend_schema定义的完整示例 > 序列化器级extend_schema_serializer定义的完整示例 > 字段级example参数值 > 自动生成的默认示例
• 字段级示例会自动和上层定义的完整请求/响应示例合并，不会产生配置冲突

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