以下是使用 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="contact@example.com"),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 Responseclass 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, OpenAPIRendererschema_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: pagein: querytype: integerrequired: falsedescription: 页码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），需在文档中配置安全策略。
