Django怎么自动生成API文档_Python集成drf-spectacular与Swagger-Python教程-PHP中文网

drf-spectacular schema 返回 404 或空 json 的常见原因是未正确配置 url 路由或未启用 schemaview，需手动注册路由、确保 spectacularapiview 正确配置并加入 installed_apps，同时设置 default_schema_class 和 security 配置以支持 jwt 认证。

django怎么自动生成api文档_python集成drf-spectacular与swagger

drf-spectacular 生成的 schema 为什么返回 404 或空 JSON？

常见原因是未正确配置 URL 路由或未启用 SchemaView。Django 3.2+ 默认不自动包含 API schema 路由，必须手动注册。

确保在 urls.py 中添加了 schema_view 的路径，且位置在 DRF 路由之前（避免被 path('api/', include(...)) 拦截）
SchemaView 必须使用 as_view()，且传入 url_name 参数（如 url_name='openapi-schema'），否则 Swagger UI 加载时会因无法解析 swagger.json 地址而失败
检查是否漏装 drf-spectacular：运行 pip install drf-spectacular 后，确认已加入 INSTALLED_APPS —— 缺少这一步会导致 SchemaView 导入失败或静默降级

Swagger UI 页面打开但报错 “Failed to load API definition”

这通常不是后端崩溃，而是前端请求的 OpenAPI JSON 地址不可达或格式异常。重点排查响应内容和 CORS。

361SCAN security check your skill python scripts

扫描并分析已安装技能，用于查看指定技能目录的名称、描述和详情，或列出所有已安装的技能。

下载

直接访问 /api/schema/（或你配置的 schema 路径），看是否返回合法 JSON；若返回 HTML（如 Django debug 页面或 404），说明路由未生效或视图未正确配置
若返回 JSON 但顶层缺少 openapi 字段（如只有 {} 或 {"error": "..."}），大概率是 SpectacularAPIView 被中间件拦截（例如登录中间件、CSRF 验证），需为该路径排除认证逻辑
开发环境常见于未配 DEFAULT_SCHEMA_CLASS：在 settings.py 的 REST_FRAMEWORK 中必须显式设置 'DEFAULT_SCHEMA_CLASS': 'drf_spectacular.openapi.AutoSchema'，否则 DRF 用默认 schema 类，不兼容 drf-spectacular

ViewSet 方法没出现在文档里，或参数缺失

drf-spectacular 默认只扫描有明确 HTTP 方法实现（list, create, retrieve 等）的 ViewSet 动作，不自动推导自定义 @action 或重写的 get_queryset() 行为。

对 @action 方法，必须加 methods= 和 detail= 参数，且建议补充 serializer_class 或 request_body/responses 装饰器，否则 schema 无法识别输入输出结构
若 ViewSet 继承自 GenericViewSet 但没混入 Mixins（如 ListModelMixin），则 drf-spectacular 不会自动添加对应 endpoint —— 需手动用 @extend_schema 注解每个方法
序列化器字段含 read_only=True 或 write_only=True 时，drf-spectacular 会自动过滤字段方向，但若用了 SerializerMethodField 且没写 to_representation 文档提示，字段可能完全消失，此时需用 @extend_schema_field 显式声明类型

如何让 Swagger 支持 JWT Bearer 认证并自动带 Token？

Swagger UI 默认不集成 DRF 的认证类，需手动告诉它怎么注入凭证。JWT 是最常踩坑的场景。

在 settings.py 中配置 SPECTACULAR_SETTINGS，加入 'SWAGGER_UI_AUTH_ACTIONS': {'JWT': {'name': 'Authorization', 'in': 'header', 'value': 'Bearer <token>'}}</token> —— 但注意这只是 UI 提示，真正生效靠 'SECURITY_DEFINITIONS'
更可靠的方式是配置 'SECURITY': [{'Bearer': []}] 并在 'COMPONENTS' 中定义 'securitySchemes'，例如：
```
{"Bearer": {"type": "http", "scheme": "bearer", "bearerFormat": "JWT"}}
```
前端 Swagger UI 输入 token 后，所有请求会自动加 Authorization: Bearer xxx 头；但后端仍需确保 TokenAuthentication 或自定义 JWT 认证类已启用，且不与 CSRF 中间件冲突（开发时可临时禁用 csrf_protect 装饰器）