如何使用Python Django集成Swagger生成自动化API文档？-Python教程-PHP中文网

应改用 drf-spectacular 替代 drf-yasg，因其兼容 django 4.2+ 和 drf 3.14+，零配置即可暴露 /swagger/ 路由并生成 openapi 3.0.3 文档；drf-yasg ≤1.20.0 因调用已被移除的私有函数 get_script_args 而报 importerror。

别装 drf-yasg，它在 django 4.2+ 上会因调用已移除的 get_script_args 直接报 importerror；改用 drf-spectacular，零配置就能跑通 /swagger/，且生成的是 openapi 3.0.3 标准文档。

为什么 drf-yasg 在 Django 4.2+ 上启动就报错？

drf-yasg ≤1.20.0 内部硬依赖 Django 的私有函数 get_script_args，该函数早在 Django 4.2 中被彻底移除。pip 默认安装的正是这个过时版本，导致项目一启动就崩在 import 阶段。

错误信息典型长这样：ImportError: cannot import name 'get_script_args'
强行降级 Django（比如回退到 4.1）不是长久之计，新安全补丁和特性全丢了
drf-spectacular 不碰任何 Django 私有 API，升级 Django 时基本无 breaking change

drf-spectacular 零配置接入三步走

只要三处改动，/swagger/ 就能立刻访问，且支持 @api_view、APIView、GenericAPIView、ViewSet 全类型视图。

执行 pip install drf-spectacular（确认安装成功，不是 drf-yasg）
在 settings.py 的 INSTALLED_APPS 里加一行：'drf_spectacular'
在主 urls.py 中注册路由（注意顺序：必须放在 path('api/', include(...)) 之前，否则会被拦截）：

from drf_spectacular.views import SpectacularAPIView, SpectacularSwaggerView, SpectacularRedocView
<p>urlpatterns = [
path('api/schema/', SpectacularAPIView.as_view(), name='schema'),
path('swagger/', SpectacularSwaggerView.as_view(url_name='schema'), name='swagger-ui'),
path('redoc/', SpectacularRedocView.as_view(url_name='schema'), name='redoc'),</p><h1>其他路由...</h1><p>]</p><div class="aritcle_card flexRow artxards">
											<div class="artcardd flexRow">
												<a class="aritcle_card_img" rel="nofollow" href="/xiazai/skill8253" title="Django Unfold"><img
														src="https://img.php.cn/upload/skill/000/000/081/179195051030769.jpg" alt="Django Unfold" onerror="this.onerror='';this.src='/static/lhimages/moren/morentu.png'" ></a>
												<div class="aritcle_card_info flexColumn">
													<a rel="nofollow" href="/xiazai/skill8253" title="Django Unfold" class="overflowclass">Django Unfold</a>
													<p class="overflowclass">提供使用 django-unfold (v0.56+) 构建高级 Django 管理界面的专业指导。当用户提及 django-unfold、unfold admin 等内容时使用此技能。</p>
												</div>
												<a rel="nofollow" href="/xiazai/skill8253" title="Django Unfold" class="aritcle_card_btn flexRow flexcenter"><b></b><span>下载</span>
												</a>
											</div>
										</div>

Schema 返回 404 或空 JSON 怎么排查？

Swagger UI 打开后提示 “Failed to load API definition”，大概率是后端没返回合法 OpenAPI JSON，而不是前端问题。

先手动访问 /api/schema/：如果返回 HTML（比如 Django debug 页面或 404），说明路由根本没注册上或 SpectacularAPIView 没导入
如果返回 {} 或 {"error": ""}，检查是否漏了 INSTALLED_APPS 里的 'drf_spectacular'，或者中间件（如登录验证、CSRF）拦截了该路径
开发环境常见遗漏：没在 REST_FRAMEWORK 里设 'DEFAULT_SCHEMA_CLASS': 'drf_spectacular.openapi.AutoSchema'，导致 DRF 用默认 schema 类，跟 drf-spectacular 不兼容
@action 方法默认不进文档——必须显式声明 methods= 和 detail=，否则直接被忽略