drf_yasg.openapi：在Python中生成易于理解的中文API文档

drf_yasg.openapi 是一个用于在 Python 中生成易于理解的中文 API 文档的工具。它基于 Django Rest Framework (DRF) 和 swagger-ui，可以自动将代码中的注释翻译成中文，并且生成带有使用示例的 API 文档。

使用 drf_yasg.openapi 可以帮助开发者快速生成清晰明了的 API 文档，提高团队的协作效率，减少沟通成本。

首先，我们需要安装 drf_yasg 和 swagger-ui：

pip install drf-yasg
pip install django-filter
pip install coreapi

接下来，在 Django 项目的 settings.py 文件中添加以下配置：

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

REST_FRAMEWORK = {
    'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.coreapi.AutoSchema',
}

然后，在项目的 urls.py 文件中添加以下代码：

from django.urls import include, path
from rest_framework import routers
from drf_yasg.views import get_schema_view
from drf_yasg import openapi

router = routers.DefaultRouter()

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,
   permission_classes=(permissions.AllowAny,),
)

urlpatterns = [
   ...
   path('', include(router.urls)),
   path('swagger<str:format>', schema_view.without_ui(cache_timeout=0), name='schema-json'),
   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'),
   ...
]

上述代码会创建一个默认的 API 路由，并且定义了三个访问 API 文档的 URL 路径，分别是 /swagger、/redoc 和 /swagger.json。这些路径都将由 drf_yasg 自动生成，包含了 API 文档的相关信息。

最后，在你的 views.py 文件中，你可以使用 drf_yasg 提供的装饰器来注释你的 API 视图函数，例如：

from drf_yasg.utils import swagger_auto_schema

@swagger_auto_schema(methods=['post'], request_body=YourSerializer)
@api_view(['POST'])
def your_view(request):
    """
    这是一个示例 API 视图函数
    ---
    parameters:
        - name: your_param
          type: str
          description: 你的参数描述
          required: true
    """
    # your code here

通过使用 @swagger_auto_schema 装饰器，你可以使用标准的 OpenAPI 规范来注释你的 API 视图函数。这些注释将被 drf_yasg 自动翻译成中文，并且包含在生成的 API 文档中。

最后，当你运行你的 Django 项目时，你可以通过访问 /swagger 路径来查看生成的中文 API 文档。你将看到所有的 API 接口信息，包括请求参数、响应数据和使用示例等。

总而言之，drf_yasg.openapi 是一个非常方便的工具，可以帮助开发者生成易于理解的中文 API 文档。通过使用标准的 OpenAPI 注释来定义 API 接口，结合 drf_yasg 自动生成的文档页面，能够减少文档编写的工作量，提高开发效率并促进团队的协作。