drf_yasg.openapi：基于DjangoRestFramework的中文文档生成工具

drf_yasg.openapi 是一款基于 DjangoRestFramework 的中文文档生成工具，它能够帮助开发者自动生成 API 接口的文档，并提供使用例子。本文将介绍 drf_yasg.openapi 的基本使用方法，并给出一些例子供参考。

首先，我们需要在我们的 Django 项目中安装 drf_yasg.openapi。可以通过执行以下命令来安装：

pip install drf_yasg

安装完成后，我们需要做一些配置工作。在项目的 settings.py 中，需要进行以下设置：

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

SWAGGER_SETTINGS = {
    'DEFAULT_INFO': 'your_project.urls.openapi_info',
}

在这个配置中，我们将 drf_yasg 添加到了 INSTALLED_APPS 中，并设置了 SWAGGER_SETTINGS。

接下来，我们需要创建一个 urls.py 文件，这里我们将定义一个函数来生成 API 文档：

from drf_yasg.views import get_schema_view
from drf_yasg import openapi

schema_view = get_schema_view(
   openapi.Info(
      title="API 文档",
      default_version='v1',
      description="API 接口文档",
      terms_of_service="https://www.example.com/policies/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'),
   ...
]

在这个例子中，我们创建了一个 schema_view，其中包含了一些基本信息，如标题、版本、描述等。我们还定义了两个 URL 路径，分别用于使用 SwaggerUI 和 Redoc 来展示 API 文档。

现在，我们已经完成了 drf_yasg.openapi 的配置，我们可以运行我们的 Django 项目，并访问 '/swagger/' 或 '/redoc/' 来查看生成的 API 文档。

下面我们来看一些使用例子。假设我们有一个 User 模型和一个对应的 UserSerializer，我们想要对它们进行 API 文档的生成。

首先，我们需要导入一些必要的类和函数：

from rest_framework.views import APIView
from rest_framework.response import Response
from drf_yasg.utils import swagger_auto_schema
from your_project.serializers import UserSerializer

接下来，我们可以定义一个继承自 APIView 的类，并使用 swagger_auto_schema 装饰类中的方法，来为这个方法添加对应的文档信息。例如，我们可以这样定义一个获取用户信息的接口：

class UserInfoView(APIView):
    @swagger_auto_schema(
        operation_description="获取用户信息",
        responses={
            200: UserSerializer,
            400: "请求参数有误",
            403: "没有权限访问",
            500: "服务器错误"
        }
    )
    def get(self, request):
        # 获取用户信息的逻辑
        ...
        serializer = UserSerializer(user)
        return Response(serializer.data)

在这个例子中，我们使用 swagger_auto_schema 装饰了 get 方法，并给它添加了一些信息，如操作描述、响应信息等。在 responses 字典中，我们指定了不同的响应码以及对应的响应内容。

通过这样的方式，我们可以为所有的 API 接口添加文档信息，并让 drf_yasg.openapi 自动生成这些接口的文档。

总结起来，drf_yasg.openapi 是一款方便易用的 DjangoRestFramework 的中文文档生成工具，它能够帮助开发者自动生成接口文档，并提供使用例子。通过简单的配置和装饰器的使用，我们可以获得清晰易懂的 API 接口文档，方便我们开发和测试。