自定也 api 文档页面信息

以下，用 django 的一个 view 举例

from drf_yasg import openapi
from drf_yasg.utils import swagger_auto_schema
from rest_framework import generics
from django.utils.decorators import method_decorator

# 定义 CustomerDetail 中 POST API 在页面显示内容
@method_decorator(name="post", decorator=swagger_auto_schema(
    operation_summary='Create Custome',
    operation_description='Create Custome',
    operation_id='customers_create',
    manual_parameters=[
          openapi.Parameter('id', openapi.IN_QUERY, description="3,4,5", type=openapi.TYPE_STRING)
    ]
    request_body=openapi.Schema(
        type=openapi.TYPE_OBJECT, 
            properties=[
                {"username": openapi.Schema(type=openapi.TYPE_STRING, enum=['admin', 'visitor'], format=openapi.FORMAT_EMAIL, description='username')},
                {"password": openapi.Schema(type=openapi.TYPE_STRING, description='password')},
            ]
    ),
    responses={
        200: CustomerDetailSerializers(),
        400: _('Request failed'),
        404: _('Not Found'),
        500: _('Server Error')
    }
))
class CustomerDetail(generics.RetrieveUpdateDestroyAPIView):
    queryset = Customer.objects.filter()
    serializer_class = CustomerDetailSerializers

openapi.Schema 参数说明

operation_summary：操作名称如下图

operation_description：接口介绍 如下图

operation_id：操作方法名如下图

manual_parameters: 修改 Parameters 中参数说明

request_body：post 发送内容 如下图

responses：响应内容 如下图

enum: 定义改字段可选的参数值，默认写第一个。如下图

model 中也会显示 enum 的可选数值

openapi.Schema 参数：

description: 字段描述
type: 字段需要什么类型的数据
             TYPE_OBJECT = "object"
             TYPE_STRING = "string"
             TYPE_NUMBER = "number"
             TYPE_INTEGER = "integer"
             TYPE_BOOLEAN = "boolean"
             TYPE_ARRAY = "array"
             TYPE_FILE = "file"

format: 进行验证的方式
             FORMAT_DATE = "date"
             FORMAT_DATETIME = "date-time"
             FORMAT_PASSWORD = "password"
             FORMAT_BINARY = "binary"
             FORMAT_BASE64 = "bytes"
             FORMAT_FLOAT = "float"
             FORMAT_DOUBLE = "double"
             FORMAT_INT32 = "int32"
             FORMAT_INT64 = "int64"
             FORMAT_EMAIL = "email"
             FORMAT_IPV4 = "ipv4"
             FORMAT_IPV6 = "ipv6"
             FORMAT_URI = "uri"
             FORMAT_UUID = "uuid"
             FORMAT_SLUG = "slug"
             FORMAT_DECIMAL = "decimal"

其他设置

默认显示 Example Value

SWAGGER_SETTINGS = {
    'DEFAULT_MODEL_RENDERING': 'example',
}

定义登录页面

SWAGGER_SETTINGS = {
    'LOGIN_URL': '/api-auth/login/',
    'LOGOUT_URL': '/api-auth/logout/',
}

设置 token 页面 如下图

SWAGGER_SETTINGS = {
    'SECURITY_DEFINITIONS': {
        'User Token': {
            'type': 'apiKey',
            'name': 'Authorization',
            'in': 'header'
        }
    },
}

image.png