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，功能更强大且维护活跃。
• 核心步骤：
- 安装库并配置
settings.py和urls.py。 - 通过装饰器或注释为视图添加接口描述。
- 访问
/swagger/查看文档。
• 注意事项：
• 确保视图继承自 DRF 的基类（如APIView）。
• 若接口涉及认证（如 JWT），需在文档中配置安全策略。