DjangoRESTSwagger配置：drf-yasg生成API文档指南

本文详细解析了在 Django REST Framework 3.10+ 环境下如何正确迁移和配置现代化 API 文档方案——用已官方推荐、稳定可靠的 drf-yasg 替代早已废弃且无法兼容的 django-rest-swagger，不仅直击旧方案因依赖 coreapi 移除导致的白屏、参数丢失、启动报错等“踩坑现场”，更手把手指导安装、路由配置、Serializer 参数精准识别、@action 方法文档化、生产环境静态资源与 HTTPS 适配等关键实践，帮你避开常见陷阱，快速生成专业、准确、可交互的 Swagger API 文档。

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 看原始输出是否合法。

本篇关于《DjangoRESTSwagger配置：drf-yasg生成API文档指南》的介绍就到此结束啦，但是学无止境，想要了解学习更多关于文章的相关知识，请关注golang学习网公众号！