Django集成Swagger：drf-yasg接口文档教程

本文详细讲解了在 Django 项目中集成 Swagger 自动生成 API 文档的关键步骤与常见陷阱，重点剖析了为何必须配置 `DEFAULT_SCHEMA_CLASS` 为 `drf_yasg.inspectors.SwaggerAutoSchema`（否则页面显示“No operations defined”）、如何正确安装注册应用、挂载路由（尤其强调 `urlconf` 参数不可或缺）、规范编写 ViewSet 和 APIView 的 docstring（格式、空行、字段注释语法），并解决了 Django 4.x+ 环境下因 `force_text` 弃用导致的 500 错误，最后提醒生产环境禁用 Swagger 路径以规避敏感信息泄露风险——堪称一份避坑指南级的 drf-yasg 实战手册。

drf-yasg 安装与基础配置为什么必须加 DEFAULT_SCHEMA_CLASS

不加这个配置，Django REST Framework 会默认用 coreapi 生成 schema，而 drf-yasg 的 UI 完全依赖它自己的 SwaggerAutoSchema。结果就是页面能打开，但所有接口都显示 “No operations defined”，点进去空空如也。

正确做法是确保 settings.py 中有：

REST_FRAMEWORK = {
    'DEFAULT_SCHEMA_CLASS': 'drf_yasg.inspectors.SwaggerAutoSchema',
}

同时确认已安装并注册了 app：

• pip install drf-yasg
• INSTALLED_APPS 里加上 'drf_yasg'

URL 路由怎么写才让 Swagger UI 正常加载

常见错误是直接把 get_schema_view 当成普通视图函数塞进 urlpatterns，漏掉参数或调用方式不对，导致 404 或 JSON 解析失败。

必须用 get_schema_view 返回的可调用对象，并显式传入 urlconf（尤其在多 URL 配置或子应用路由时）：

from drf_yasg.views import get_schema_view
from drf_yasg import openapi
<p>schema_view = get_schema_view(
openapi.Info(
title="API",
default_version='v1',
),
public=True,
urlconf='myproject.urls',  # ⚠️ 这个不能少，否则找不到视图
)</p>

然后在主 urls.py 中这样挂载：

• path('swagger/', schema_view.with_ui('swagger', cache_timeout=0), name='schema-swagger-ui')
• path('redoc/', schema_view.with_ui('redoc', cache_timeout=0), name='schema-redoc')

ViewSet 和 APIView 的 docstring 怎么写才能被正确解析

drf-yasg 默认只读取类 docstring，且要求格式严格：第一行是简短描述，空一行后是详细说明（支持简单 reStructuredText），再空一行才是参数、返回值等字段注释。

容易踩的坑：

• 用 # 写注释 → 不识别，必须用 """ 包裹的 docstring
• 没空行分隔 → 整段被当标题，参数字段（如 :param:）被忽略
• 字段名拼错，比如写成 :param str user_id: → 应为 :param user_id:，类型写在冒号后空格后：:type user_id: int

示例有效写法：

class UserListView(APIView):
    """获取用户列表
<pre class="brush:python;toolbar:false;">支持分页和关键词搜索。

:param search: 用户名模糊匹配
:type search: str
:param page: 页码
:type page: int
"""
def get(self, request):
    ...

为什么生产环境访问 Swagger 页面报 500 或提示 ImportError: cannot import name 'force_text'

这是 drf-yasg 旧版本（django.utils.encoding.force_text，新版本 Django 改成了 force_str。

解决方法只有两个：

• 升级到 drf-yasg >= 1.20.0（推荐）：pip install --upgrade drf-yasg
• 降级 Django 到 3.2.x（不推荐，安全与维护风险高）

升级后如果仍报错，检查是否残留本地修改或缓存：清空 __pycache__、重启服务、确认 pip show drf-yasg 输出的版本号准确。

另外，别在生产环境暴露 /swagger/ 路径——即使加了权限控制，UI 本身会把所有接口定义吐给前端，敏感字段（如 password）若没在 serializer 中显式设为 write_only=True，就可能被文档直接展示出来。

理论要掌握，实操不能落！以上关于《Django集成Swagger：drf-yasg接口文档教程》的详细介绍，大家都掌握了吧！如果想要继续提升自己的能力，那么就来关注golang学习网公众号吧！