如何使用drf_yasg.openapi为Django项目生成中文API文档

要为Django项目生成中文API文档，并带有使用示例，可以使用drf_yasg.openapi库。以下是一些步骤来实现这个目标：

1. 安装依赖：

在项目的虚拟环境中，使用pip命令安装所需的依赖项：

   pip install drf_yasg
   

2. 修改项目的settings.py文件：

在INSTALLED_APPS中添加以下两个应用程序：

   'drf_yasg',
   'django.contrib.sites',
   

并在文件的末尾添加以下配置：

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

3. 创建一个urls.py文件：

在项目的urls.py文件所在目录中，创建一个新的urls.py文件，并添加以下内容：

   from django.urls import path, include
   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文档描述",
       ),
       public=True,
       permission_classes=(permissions.AllowAny,),
   )

   urlpatterns = [
       path('swagger(<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'),
       # 其他项目路径
   ]
   

请务必替换标题和描述为你项目的实际信息。

4. 创建一个openapi_info.py文件：

在项目的urls.py文件所在目录中，创建一个名为openapi_info.py的文件，并添加以下内容：

   from django.contrib.sites.shortcuts import get_current_site

   def openapi_info():
       return {
           "version": "1.0.0",
           "title": "API文档标题",
           "description": "API文档描述",
           "contact": {
               "name": "联系人名字",
               "url": f"https://{get_current_site(None).domain}/",
               "email": "联系人邮箱"
           },
           "license": {
               "name": "许可证名字",
               "url": "许可证URL"
           },
           "servers": [
               {
                   "url": f"https://{get_current_site(None).domain}/",
                   "description": "主机描述"
               }
           ]
       }
   

请按照你项目的实际情况填写各个字段的值。

5. 为每个API视图编写Swagger文档：

在每个API视图的注释中，使用Swagger规范的方式编写文档。以下是一个示例：

   class MyView(APIView):
       """
       get:
       获取对象列表

       post:
       创建一个新的对象
       """
       def get(self, request):
           """
           获取对象列表的详细描述
           ---
           parameters:
             - name: page
               in: query
               type: integer
               required: false
               description: 分页的页码
           responses:
             200:
               description: 成功获取对象列表
           """
           # 实际操作

       def post(self, request):
           """
           创建一个新的对象的详细描述
           ---
           parameters:
             - name: name
               in: formData
               type: string
               required: true
               description: 对象的名称
           responses:
             201:
               description: 成功创建对象
           """
           # 实际操作
   

6. 运行项目：

在命令行中使用以下命令运行项目：

   python manage.py runserver
   

7. 访问Swagger UI：

在浏览器中访问 http://localhost:8000/swagger/（假设项目运行在本地的8000端口）。你将看到一个自动生成的API文档，其中包含了每个API视图的详细描述和使用示例。

以上是使用drf_yasg.openapi为Django项目生成中文API文档的简要步骤。你可以根据你的项目需求和Swagger文档规范对其进行进一步定制和优化。