drf-yasg 是 Django REST Framework 3.10+ 唯一推荐的 Swagger 文档方案，因 django-rest-swagger 已废弃、依赖被移除的 coreapi 且 PyPI 标为 deprecated，安装后实为空壳包，会导致白屏、参数不识别等错误。
drf-yasg 是目前 Django REST Framework 项目里最靠谱的 Swagger 文档生成方案，django-rest-swagger 已废弃且不兼容 DRF 3.10+，硬配会报 AttributeError: 'AutoSchema' object has no attribute 'get_link' 这类错。
为什么不能继续用 django-rest-swagger
它依赖过时的 coreapi，而 DRF 3.10+ 彻底移除了对 coreapi 的支持；官方仓库早在 2019 年就归档（Archived），PyPI 上也标了 deprecated。你 pip install 的最新版实际是空壳包，运行就炸。
常见错误现象：
- 访问
/docs/页面白屏，控制台报ReferenceError: SwaggerUIBundle is not defined - 启动时报
ImportError: cannot import name 'SchemaGenerator' - 文档里所有接口参数都显示为
string，连 request body 都不识别Serializer
drf-yasg 安装与基础路由配置
先卸掉旧包：pip uninstall django-rest-swagger，再装新方案：
pip install drf-yasg
在 urls.py 中替换原路由：
- 删掉原来的
url(r'^docs/', include('rest_framework_swagger.urls')) - 加上
from drf_yasg.views import get_schema_view和对应路由 -
get_schema_view()必须传public=True，否则登录后才显示（默认行为） - 路径别写成
/swagger/就完事——要加.as_cached_view()否则每次请求都重生成，拖慢响应
示例片段：
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',
),
public=True,
)
urlpatterns += [
url(r'^swagger(?P<format>\.json|\.yaml)$', schema_view.without_ui(cache_timeout=0), name='schema-json'),
url(r'^swagger/$', schema_view.with_ui('swagger', cache_timeout=0), name='schema-swagger-ui'),
]
Serializer 参数不显示？检查 viewset 或 APIView 的 schema 类
drf-yasg 默认靠 AutoSchema 解析视图，但如果你手动写了 get_serializer_class() 或用了 @action 方法，它很可能抓不住参数结构。
- ViewSet 里每个
@action方法必须显式加methods=['post']，否则 schema 不识别 HTTP 动词 - 如果 request body 是自定义
Serializer，得在方法上加装饰器：@swagger_auto_schema(request_body=MySerializer) - Query 参数默认不自动提取，要用
@swagger_auto_schema(manual_parameters=[...])补充openapi.Parameter列表 - 别依赖
serializer_class全局设置——APIView子类里没写serializer_class，AutoSchema就当没这回事
生产环境部署时容易漏掉的两件事
本地跑通不等于线上能用。两个高频翻车点：
- 静态文件没收集：
drf-yasg的 UI 依赖swagger-ui-dist，但它的 JS/CSS 不进STATIC_ROOT，得在settings.py加SWAGGER_SETTINGS = {'DEFAULT_MODEL_RENDERING': 'example'}并确认STATICFILES_DIRS包含drf_yasg的 static 目录（或改用 CDN） - HTTPS 下加载 HTTP 资源被拦截：Swagger UI 默认用
window.location.protocol拼地址，Nginx 反代后可能协议头丢失，需加SECURE_PROXY_SSL_HEADER = ('HTTP_X_FORWARDED_PROTO', 'https')
复杂点在于：schema 生成逻辑和视图执行逻辑耦合很深，一个 get_queryset() 里抛异常，整个文档页面就 500；调试时别只刷 UI 页面，先 curl /swagger.json 看原始输出是否合法。
