如何在drf-yasg的swagger_auto_schema中为request_body指定示例值

你可以通过@swagger_auto_schema装饰器的request_body参数完成配置，常用实现方式有两种：

方式一：基于Serializer定义（推荐） #

Serializer字段直接声明example属性即可自动生成示例，适合请求体结构复杂、复用性高的场景：

1. 首先定义请求Serializer：

from rest_framework import serializers

class UserLoginRequestSerializer(serializers.Serializer):
    username = serializers.CharField(
        max_length=32,
        help_text="登录用户名",
        example="test_user_001"
    )
    password = serializers.CharField(
        min_length=6,
        help_text="登录密码",
        example="Test@123456"
    )
    remember_me = serializers.BooleanField(
        help_text="是否记住7天登录状态",
        default=False,
        example=True
    )

2. 在视图上绑定装饰器指定请求Serializer：

from drf_yasg.utils import swagger_auto_schema
from rest_framework.views import APIView
from rest_framework.response import Response

class UserLoginView(APIView):
    @swagger_auto_schema(
        request_body=UserLoginRequestSerializer,
        operation_summary="用户登录接口"
    )
    def post(self, request):
        # 你的业务逻辑
        return Response({"status": "ok"})

方式二：手动构造OpenAPI Schema #

适合请求体结构简单、不需要复用Serializer的场景，直接在装饰器内定义结构和示例即可：

from drf_yasg.utils import swagger_auto_schema
from drf_yasg import openapi
from rest_framework.views import APIView
from rest_framework.response import Response

class UserLoginView(APIView):
    @swagger_auto_schema(
        request_body=openapi.Schema(
            type=openapi.TYPE_OBJECT,
            required=["username", "password"],
            properties={
                "username": openapi.Schema(type=openapi.TYPE_STRING, description="登录用户名", example="test_user_001"),
                "password": openapi.Schema(type=openapi.TYPE_STRING, description="登录密码", example="Test@123456"),
                "remember_me": openapi.Schema(type=openapi.TYPE_BOOLEAN, description="是否记住7天登录状态", example=True)
            },
            # 也可统一指定整个请求体的示例，优先级高于单个字段的example
            example={
                "username": "test_user_001",
                "password": "Test@123456",
                "remember_me": False
            }
        ),
        operation_summary="用户登录接口"
    )
    def post(self, request):
        # 你的业务逻辑
        return Response({"status": "ok"})

如果是函数视图或者ViewSet的自定义action，只需要把@swagger_auto_schema装饰器加在对应的处理函数上即可，配置规则完全一致。

内容的提问来源于stack exchange，提问作者carlos de la morena