使用DRF_Yasg.openapiInfo()构建OpenAPI文档

DRF_Yasg是一个用于Django Rest Framework的扩展库，用于自动生成OpenAPI（以前称为Swagger）文档。它提供了一个方便的方式来定义API的结构、参数和响应，并将其转化为可视化的文档。DRF_Yasg.openapiInfo()是其主要功能之一，它用于构建OpenAPI文档。

使用DRF_Yasg.openapiInfo()可以将API视图函数、序列化器和视图集等内容转化为OpenAPI文档。以下是一个带有使用例子的详细解释。

首先，在Django项目的settings.py文件中安装DRF_Yasg库，并将其添加到INSTALLED_APPS列表中。

INSTALLED_APPS = [
    ...
    'drf_yasg',
    ...
]

然后，在项目的urls.py文件中添加DRF_Yasg所需的URL配置。

from django.contrib import admin
from django.urls import path, include
from rest_framework import routers
from rest_framework.documentation import include_docs_urls

import drf_yasg.views
import drf_yasg.urls

router = routers.DefaultRouter()

# 添加你的API视图集
router.register(r'users', views.UserViewSet)

urlpatterns = [
    path('', include(router.urls)),
    path('api-auth/', include('rest_framework.urls')),
    path('admin/', admin.site.urls),

    # 添加DRF_Yasg的URL配置
    path('swagger<str:url>', include(drf_yasg.urls)),
    path('docs/', include_docs_urls(title='My API')),
]

现在，你可以在浏览器中访问/docs/，将看到自动生成的API文档。注意，此时它只包含了基本的信息，如API根路径和认证方式。

为了更详细地定义API，我们需要在视图函数或视图集的注释中添加OpenAPI的标签和注解。

class UserViewSet(viewsets.ModelViewSet):
    """
    API endpoint that allows users to be viewed or edited.
    """

    queryset = User.objects.all().order_by('-date_joined')
    serializer_class = UserSerializer

    @swagger_auto_schema(responses={200: UserSerializer(many=True)})
    def list(self, request, *args, **kwargs):
        """
        Return a list of all the users.
        """
        return super().list(request, *args, **kwargs)

上面的例子中，我们在视图集的注释中添加了API的描述文字。在list方法上，我们使用了swagger_auto_schema装饰器，用于指定响应的数据类型和格式。

使用DRF_Yasg.openapiInfo()来创建OpenAPI文档非常简单。在项目的serializers.py文件中，我们可以将API的序列化器转化为OpenAPI的数据模型。

from drf_yasg import openapi

class UserSerializer(serializers.ModelSerializer):
    """
    Serializer for User model.
    """

    class Meta:
        model = User
        fields = '__all__'

    openapi_schema = {
        'type': 'object',
        'properties': {
            'id': {
                'type': 'integer',
                'format': 'int32',
            },
            'username': {
                'type': 'string',
            },
            'email': {
                'type': 'string',
                'format': 'email',
            },
        },
    }

完成上述步骤后，当我们再次访问/docs/时，将能看到更详细的API文档，包括请求和响应的数据结构、参数和示例。

总之，DRF_Yasg.openapiInfo()是一个方便的工具，可以帮助我们自动生成基于Django Rest Framework的OpenAPI文档。我们可以使用适当的注释和装饰器来定义API的结构和参数。通过这种方式，我们可以为我们的API提供专业且易于理解的文档，从而提高开发人员的工作效率。