django自动添加接口文档

以下是使用 Django 和 django-rest-swagger （或替代方案 drf-yasg ）生成 API 接口文档的详细指南。由于 django-rest-swagger 已停止维护，推荐使用 drf-yasg（支持 Swagger 2.0 和 OpenAPI 3.0），但两种方法均会说明：

---

一、方案选择与安装

1. 方案对比

库名	维护状态	支持规范	功能特点
django-rest-swagger	已弃用	Swagger 2.0	旧项目兼容，文档生成简单
drf-yasg	活跃维护	OpenAPI 3.0	功能强大，支持更详细的配置

2. 安装推荐库（drf-yasg）

# 安装 drf-yasg（推荐）
pip install drf-yasg

# 或安装旧版 django-rest-swagger（不推荐）
# pip install django-rest-swagger==2.2.0

---

二、配置 drf-yasg 生成接口文档（推荐）

1. 配置 settings.py

# settings.py
INSTALLED_APPS = [
    ...
    'rest_framework',
    'drf_yasg',  # 添加 drf-yasg
]

# 可选：配置 DRF 的默认权限（按需设置）
REST_FRAMEWORK = {
    'DEFAULT_PERMISSION_CLASSES': [
        'rest_framework.permissions.AllowAny',
    ]
}

2. 配置 URL 路由

# urls.py
from django.urls import path, include
from rest_framework import permissions
from drf_yasg.views import get_schema_view
from drf_yasg import openapi

# 定义 Swagger 文档视图
schema_view = get_schema_view(
    openapi.Info(
        title="API 文档",
        default_version='v1',
        description="项目接口文档",
        terms_of_service="https://example.com/terms/",
        contact=openapi.Contact(email="[email protected]"),
        license=openapi.License(name="MIT License"),
    ),
    public=True,
    permission_classes=(permissions.AllowAny,),  # 控制文档访问权限
)

urlpatterns = [
    # Swagger 文档路由
    path('swagger/', schema_view.with_ui('swagger', cache_timeout=0), name='swagger-ui'),
    path('redoc/', schema_view.with_ui('redoc', cache_timeout=0), name='redoc'),
    
    # 其他 API 路由
    path('api/', include('myapp.urls')),
]

3. 为视图添加文档注释

在视图（如 views.py）中使用装饰器或 YAML 注释描述接口：

from drf_yasg.utils import swagger_auto_schema
from rest_framework.views import APIView
from rest_framework.response import Response

class UserListView(APIView):
    @swagger_auto_schema(
        operation_description="获取用户列表",
        manual_parameters=[
            openapi.Parameter(
                'page', 
                openapi.IN_QUERY, 
                description="页码", 
                type=openapi.TYPE_INTEGER
            ),
        ],
        responses={200: '成功获取用户列表'}
    )
    def get(self, request):
        return Response({"users": []})

4. 访问文档

• Swagger UI : http://localhost:8000/swagger/

• ReDoc : http://localhost:8000/redoc/

---

三、使用旧版 django-rest-swagger（不推荐）

1. 配置 settings.py

# settings.py
INSTALLED_APPS = [
    ...
    'rest_framework',
    'rest_framework_swagger',  # 添加 django-rest-swagger
]

# 配置 Swagger 设置
SWAGGER_SETTINGS = {
    'SECURITY_DEFINITIONS': {
        'basic': {
            'type': 'basic'
        }
    },
    'USE_SESSION_AUTH': False,  # 是否启用 Django 的 Session 认证
}

2. 配置 URL 路由

# urls.py
from django.urls import path
from rest_framework.schemas import get_schema_view
from rest_framework_swagger.renderers import SwaggerUIRenderer, OpenAPIRenderer

schema_view = get_schema_view(
    title="API 文档",
    renderer_classes=[OpenAPIRenderer, SwaggerUIRenderer]
)

urlpatterns = [
    path('swagger/', schema_view, name='swagger'),
    path('api/', include('myapp.urls')),
]

3. 为视图添加注释

在视图类或函数中使用文档字符串（YAML 格式）：

class UserListView(APIView):
    def get(self, request):
        """
        获取用户列表

        ---
        parameters:
            - name: page
              in: query
              type: integer
              required: false
              description: 页码
        responses:
            200:
                description: 成功返回用户列表
        """
        return Response({"users": []})

4. 访问文档

• 访问 http://localhost:8000/swagger/

---

四、常见问题与优化

1. 文档不显示接口

• 原因 : 视图未继承 APIView 或未配置路由。

• 解决 : 确保所有接口使用 DRF 的视图类（如 APIView, ViewSet），并正确注册到路由。

2. 认证配置

• 场景 : 需要登录才能访问 Swagger 文档。

• 配置 （在 settings.py 中）：

SWAGGER_SETTINGS = {
    'LOGIN_URL': '/admin/login/',  # 登录地址
    'LOGOUT_URL': '/admin/logout/',
    'USE_SESSION_AUTH': True,
}

3. 自定义文档样式

• 方法 : 覆盖默认模板或使用 drf-yasg 的扩展参数：

schema_view = get_schema_view(
    ...
    patterns=[...],  # 指定要包含的路由
    generator_class='myapp.schemas.CustomSchemaGenerator',  # 自定义生成器
)

4. 隐藏特定接口

• 使用 drf_yasg:

@swagger_auto_schema(auto_schema=None)
def my_view(request):
    ...

---

五、总结

• 推荐方案 : 使用 drf-yasg ，功能更强大且维护活跃。

• 核心步骤：

1. 安装库并配置 settings.py 和 urls.py。
2. 通过装饰器或注释为视图添加接口描述。
3. 访问 /swagger/ 查看文档。
   • 注意事项 ：
   • 确保视图继承自 DRF 的基类（如 APIView）。
   • 若接口涉及认证（如 JWT），需在文档中配置安全策略。