DRF_Yasg.openapiInfo()核心功能介绍

DRF-Yasg（Django Rest Framework Swagger）是一个强大的Django REST框架的插件，用于自动生成和展示API文档。它使用OpenAPI规范（以前称为Swagger）来描述API，并提供了一个漂亮的UI界面来查看和测试API。

DRF-Yasg有许多强大的功能，下面是一些核心功能的介绍，并附有使用例子。

1. 自动生成API文档

DRF-Yasg可以自动检测您的Django REST框架应用程序中的视图和模型以生成API文档。您只需简单地将DRF-Yasg的配置添加到您的项目中，并设置要生成文档的URL和API视图。下面是一个基本的示例：

from django.urls import path
from .views import MyAPIView
from drf_yasg.views import get_schema_view
from drf_yasg import openapi

schema_view = get_schema_view(
    openapi.Info(
        title="My API",
        default_version='v1',
        description="My API description",
        terms_of_service="https://www.example.com/terms/",
        contact=openapi.Contact(email="contact@example.com"),
        license=openapi.License(name="BSD License"),
    ),
    public=True,
)

urlpatterns = [
    path('swagger/', schema_view.with_ui('swagger', cache_timeout=0), name='schema-swagger-ui'),
    path('redoc/', schema_view.with_ui('redoc', cache_timeout=0), name='schema-redoc'),
    path('my-api/', MyAPIView.as_view(), name='my-api'),
]

在上面的代码中，我们定义了一个名为My API的API，版本为v1。我们还设置了一些其他的信息，例如描述、服务条款、联系信息和许可证。然后，我们将swagger和redoc UI添加到URL中，并将MyAPIView视图添加到my-api/ URL中。

2. 自定义API文档

DRF-Yasg允许您自定义API文档，以便更好地满足您的需求。您可以使用装饰器、字段扩展、操作扩展和自定义渲染器等功能来添加更多信息和控制API文档的呈现方式。下面是一个使用装饰器自定义API文档的示例：

from drf_yasg.utils import swagger_auto_schema

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

在上面的代码中，我们使用swagger_auto_schema装饰器指定了post方法的操作描述、请求体和响应。这将在API文档中显示为详细的说明和示例请求和响应。您还可以使用其它参数来自定义相关内容，例如query参数、headers、异常、安全等。

3. 支持分页和过滤器

DRF-Yasg支持Django REST框架的分页和过滤器功能。它会自动检测您的视图和模型中的分页器和过滤器，并将它们添加到API文档中。您可以在UI界面中使用这些参数来测试API的分页和过滤功能。下面是一个示例：

from rest_framework.pagination import PageNumberPagination
from drf_yasg import openapi

class MyPagination(PageNumberPagination):
    page_size = 10

schema_view = get_schema_view(
    ...
    paginator_class=MyPagination,
    public=True,
)

在上面的代码中，我们定义了一个名为MyPagination的分页器，每页显示10个结果。然后，我们将其添加到get_schema_view的参数中。DRF-Yasg将自动检测到它，并在API文档中添加分页参数和示例请求。

4. 支持认证和权限

DRF-Yasg支持Django REST框架的认证和权限功能。它会自动检测您的视图和模型中的认证类和权限类，并将它们添加到API文档中。您可以在UI界面中使用这些参数来测试API的认证和权限。下面是一个示例：

from rest_framework.authentication import TokenAuthentication
from rest_framework.permissions import IsAuthenticated
from drf_yasg import openapi

schema_view = get_schema_view(
    ...
    authentication_classes=[TokenAuthentication],
    permission_classes=[IsAuthenticated],
    public=True,
)

在上面的代码中，我们将TokenAuthentication和IsAuthenticated添加到get_schema_view的参数中。DRF-Yasg将自动检测到它们，并在API文档中指示需要认证和权限的操作。

DRF-Yasg还有许多其他有用的功能，例如API标签、响应注释、深度嵌套模型、自定义样式和脚本等。这些功能使得DRF-Yasg成为一个强大的工具，用于生成和展示Django REST框架应用程序的API文档。无论您是开发人员还是API的使用者，都可以受益于这个优秀的插件。