DRF_Yasg.openapiInfo()高级用法指南

DRF-YASG是一个用于自动生成OpenAPI（以前称为Swagger）规范的库，它与Django REST Framework（DRF）无缝集成。DRF-YASG提供了许多高级用法，可以帮助我们更好地定制和控制生成的OpenAPI文档。

在这篇文章中，我将向您介绍DRF-YASG的一些高级用法，并提供一些使用例子。

1. 配置操作和视图集的描述

DRF-YASG允许您在生成的OpenAPI规范中为每个操作和视图集提供自定义描述。您可以使用@swagger_auto_schema装饰器来添加描述。

from drf_yasg.utils import swagger_auto_schema

@swagger_auto_schema(
    operation_description="Create a new user",
    request_body=UserSerializer,
    responses={201: UserSerializer}
)
@api_view(['POST'])
def create_user(request):
    # 创建用户的逻辑
    pass

@extend_schema(
    description="Get a list of all users",
    responses=UserSerializer(many=True)
)
@api_view(['GET'])
def list_users(request):
    # 获取所有用户的逻辑
    pass

在上面的例子中，@swagger_auto_schema装饰器为create_user视图设置了操作描述，用UserSerializer指定了请求体和响应模式。

@extend_schema装饰器可以用于为整个视图集添加描述。

2. 定制请求体和响应模式

DRF-YASG允许您定制请求体和响应模式的信息。您可以使用@schema装饰器来设置请求体和响应模式的说明和示例。

from drf_yasg import openapi

@swagger_auto_schema(
    request_body=openapi.Schema(
        type=openapi.TYPE_OBJECT,
        properties={
            'username': openapi.Schema(type=openapi.TYPE_STRING),
            'password': openapi.Schema(type=openapi.TYPE_STRING, format='password')
        },
        required=['username', 'password']
    )
)
@api_view(['POST'])
def create_user(request):
    # 创建用户的逻辑
    pass

@swagger_auto_schema(
    responses={
        200: openapi.Schema(
            type=openapi.TYPE_OBJECT,
            properties={
                'id': openapi.Schema(type=openapi.TYPE_INTEGER, format=openapi.FORMAT_INT32),
                'username': openapi.Schema(type=openapi.TYPE_STRING),
                'email': openapi.Schema(type=openapi.TYPE_STRING, format=openapi.FORMAT_EMAIL)
            }
        )
    }
)
@api_view(['GET'])
def get_user(request, user_id):
    # 获取用户的逻辑
    pass

在上面的例子中，@swagger_auto_schema装饰器使用@schema装饰器为create_user视图设置了请求体模式，并使用@schema装饰器为get_user视图设置了响应模式。

3. 使用操作扩展模式

DRF-YASG使用操作扩展模式，允许您添加更多自定义操作字段。您可以使用@extend_schema装饰器来添加操作字段。

from drf_yasg.extensions import ExtParameters

@extend_schema(
    parameters=[
        ExtParameters.LimitOffsetField(),
        ExtParameters.SearchFilterField(),
        ExtParameters.OrderingFilterField()
    ]
)
@api_view(['GET'])
def list_users(request):
    # 获取所有用户的逻辑
    pass

在上面的例子中，@extend_schema装饰器使用ExtParameters扩展添加了LimitOffsetField，SearchFilterField和OrderingFilterField参数。

4. 定制分页器

DRF-YASG允许您定制分页器的信息。您可以使用@extend_schema装饰器来设置分页器的描述。

from rest_framework.pagination import LimitOffsetPagination

@extend_schema(
    pagination_class=LimitOffsetPagination,
    list_serializer_class=UserSerializer
)
@swagger_auto_schema(
    manual_parameters=[
        ExtParameters.LimitOffsetField(),
        ExtParameters.SearchFilterField(),
        ExtParameters.OrderingFilterField()
    ]
)
@api_view(['GET'])
def list_users(request):
    # 获取所有用户的逻辑
    pass

在上面的例子中，@extend_schema装饰器使用pagination_class参数设置了分页器类，并使用@swagger_auto_schema装饰器添加了分页器的参数描述。

以上是DRF-YASG的一些高级用法和使用例子，它们可以帮助您更好地定制和控制生成的OpenAPI文档。希望这篇文章对您有所帮助！