Django 集成 Swagger

以下是 Django 集成 Swagger 的安装及配置方法，基于当前主流工具推荐两种方案（drf-yasg 和 drf-spectacular），请根据项目需求选择：

方案一：使用 drf-yasg（支持 Swagger 2.0）

1. 安装依赖

pip install drf-yasg2 # 兼容最新版 Django 和 DRF411

2. 配置 settings.py

INSTALLED_APPS = [
    ...
    'rest_framework',
    'drf_yasg',
]
 
# 可选：Swagger 自定义配置 
SWAGGER_SETTINGS = {
    'SECURITY_DEFINITIONS': {
        'basic': {'type': 'basic'}
    },
    'JSON_EDITOR': True,  # 启用 JSON 输入框 
    'OPERATIONS_SORTER': 'alpha'  # 接口按字母排序 
}

3. 配置 urls.py

from drf_yasg.views  import get_schema_view 
from drf_yasg import openapi 
 
schema_view = get_schema_view(
    openapi.Info(
        title="API Docs",
        default_version='v1',
        description="接口文档说明",
    ),
    public=True,
)
 
urlpatterns = [
    ...
    path('swagger/', schema_view.with_ui('swagger',  cache_timeout=0)),
    path('redoc/', schema_view.with_ui('redoc',  cache_timeout=0)),
]

方案二：使用 drf-spectacular（支持 OpenAPI 3.0）

1. 安装依赖

pip install drf-spectacular  # 推荐新项目使用

2. 配置 settings.py

INSTALLED_APPS = [
    ...
    'rest_framework',
    'drf_spectacular',
]
 
REST_FRAMEWORK = {
    'DEFAULT_SCHEMA_CLASS': 'drf_spectacular.openapi.AutoSchema' 
}

# 自定义 OpenAPI 配置 
SPECTACULAR_SETTINGS = {
    'TITLE': '项目 API',
    'DESCRIPTION': '接口文档详细说明',
    'VERSION': '1.0.0',
    'SERVE_INCLUDE_SCHEMA': False,  # 隐藏 Schema 信息 
}

3. 配置 urls.py

from drf_spectacular.views  import SpectacularAPIView, SpectacularSwaggerView 
 
urlpatterns = [
    ...
    path('schema/', SpectacularAPIView.as_view(),  name='schema'),
    path('swagger/', SpectacularSwaggerView.as_view(url_name='schema'),  name='swagger-ui'),
]

注意事项

版本兼容性
若使用 django-rest-swagger，需注意该库已弃用且仅支持旧版 Django/DRF。
drf-yasg2 是 drf-yasg 的维护分支，兼容最新版本。
接口注释规范
使用 @swagger_auto_schema（drf-yasg）或 @extend_schema（drf-spectacular）装饰器自定义接口描述。
测试访问
启动服务后，通过以下路径访问：
Swagger UI：http://localhost:8000/swagger/
Redoc：http://localhost:8000/redoc/
工具对比

工具	支持的规范	特点
drf-yasg2	Swagger 2.0	配置简单，社区资源丰富1
drf-spectacular	OpenAPI 3.0	功能更现代，支持分层文档35

根据项目需求选择合适的工具，新项目推荐使用 drf-spectacular 以获得更好的扩展性。