如何在Django REST Framework的swagger_auto_schema中添加示例？

要给接口添加输入输出的JSON示例，你可以通过以下方式修改@swagger_auto_schema的配置：

1. 添加请求体输入示例 #

在request_body对应的openapi.Schema中，直接添加example字段，传入符合格式的JSON对象即可。

2. 添加响应输出示例 #

将原本响应中简单的字符串描述，替换为openapi.Response对象，通过examples字段指定JSON格式的响应示例。

修改后的完整代码 #

from drf_yasg import openapi
from drf_yasg.utils import swagger_auto_schema

@swagger_auto_schema(
    methods=['post'],
    request_body=openapi.Schema(
        type=openapi.TYPE_OBJECT,
        required=['name', 'lastname', 'username', 'password', 'confirm_password'],
        properties={
            'name': openapi.Schema(type=openapi.TYPE_STRING, max_length=50),
            'lastname': openapi.Schema(type=openapi.TYPE_STRING, max_length=50),
            'username': openapi.Schema(type=openapi.TYPE_STRING, description="it must be unique for every person. it must not contain space or invalid characters."),
            'password': openapi.Schema(type=openapi.TYPE_STRING),
            'confirm_password': openapi.Schema(type=openapi.TYPE_STRING, description="password and confirm password must be same"),
            'national_code': openapi.Schema(type=openapi.TYPE_STRING),
            'license_code': openapi.Schema(type=openapi.TYPE_STRING),
            'birthdate': openapi.Schema(type=openapi.TYPE_STRING, default="yyyy-mm-dd", description="it is actually a date"),
            'gender': openapi.Schema(type=openapi.TYPE_INTEGER, enum=[(1, _("Male")), (2, _("Female"))]),
            'address': openapi.Schema(type=openapi.TYPE_STRING),
            'email': openapi.Schema(type=openapi.TYPE_STRING),
            'phone_number': openapi.Schema(type=openapi.TYPE_STRING),
            'image_code': openapi.Schema(type=openapi.TYPE_STRING, description="it is the base64 code of the image"),
        },
        # 请求体示例
        example={
            "name": "John",
            "lastname": "Doe",
            "username": "johndoe123",
            "password": "StrongPass123!",
            "confirm_password": "StrongPass123!",
            "national_code": "1234567890",
            "license_code": "LIC12345",
            "birthdate": "1990-01-01",
            "gender": 1,
            "address": "123 Main St, City",
            "email": "john.doe@example.com",
            "phone_number": "+1234567890",
            "image_code": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg=="
        }
    ),
    responses={
        # 200响应示例
        200: openapi.Response(
            description='Staff Created Successfully!',
            examples={
                'application/json': {
                    "status": "success",
                    "message": "Staff created successfully",
                    "data": {
                        "id": 1,
                        "name": "John",
                        "lastname": "Doe",
                        "username": "johndoe123",
                        "national_code": "1234567890",
                        "license_code": "LIC12345",
                        "birthdate": "1990-01-01",
                        "gender": "Male",
                        "address": "123 Main St, City",
                        "email": "john.doe@example.com",
                        "phone_number": "+1234567890",
                        "role": "staff",
                        "customer": "customer_123"
                    }
                }
            }
        ),
        # 400响应示例
        400: openapi.Response(
            description='Error!',
            examples={
                'application/json': {
                    "status": "error",
                    "message": "Invalid input data",
                    "errors": {
                        "username": ["This username is already taken."],
                        "confirm_password": ["Passwords do not match."]
                    }
                }
            }
        ),
    },
    operation_description="Add a new staff API. The role field(=staff), customer field(=parent.customer) and parent would be set automatically",
)

说明 #

• 请求体的example会在Swagger界面的「Example Value」区域展示，直观呈现正确的输入格式。
• 响应的examples针对JSON类型设置了成功、错误两种场景的返回结构，用户可以直接看到接口的输出样式。

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