Python中怎么为Django的API自动生成Swagger在线文档？-Python教程-PHP中文网

drf-spectacular是目前最省心、兼容性最好、真正开箱即用的drf openapi文档方案，需安装配置、补全serializer注释及@extend_schema标注、显式声明认证与安全定义。

python中怎么为django的api自动生成swagger在线文档？

用 drf-spectacular 是目前最省心、兼容性最好、且真正开箱即用的方案。Django REST Framework 官方不维护 Swagger 集成，旧方案如 django-rest-swagger 已停更多年，强行用会卡在 DRF 3.12+ 和 OpenAPI 3 的兼容问题上。

安装与基础配置要一步到位

别碰 coreapi 或手动写 schema.yml——它们要么已弃用，要么维护成本极高。直接装 drf-spectacular 并配进 INSTALLED_APPS 和 URL 路由：

运行 pip install drf-spectacular
在 settings.py 的 INSTALLED_APPS 中加入 'drf_spectacular'
在主 urls.py 里加路由：path('api/schema/', SpectacularAPIView.as_view(), name='schema') 和 path('api/schema/swagger-ui/', SpectacularSwaggerView.as_view(url_name='schema'), name='swagger-ui')
确保你的 API 视图类继承自 APIView、GenericAPIView 或 ViewSet，且用了标准的 serializer_class 或 get_serializer_class()

字段描述和请求体不显示？检查 serializer 注释和 @extend_schema

drf-spectacular 默认靠 serializer 的 help_text、label 和 docstring 推导字段说明。如果 Swagger 里字段没描述、或 POST body 空白，大概率是这些地方没填：

python全能编程助手

SkillSub Pro - Python 题解与代码注释双功能技能功能概述SkillSub Pro - Python 题解与代码注释双功能技能是一项面向实际任务的技能，主要用于SkillSub Pro 是一个 Python 题解生成与代码注释的双功能合体技能，专为学生、算法学习者和开发者设计；✅ 一个技能，两种用途：；核心要点📝 题解模式：输入题目/题号，自动生成完整 Python 题解（含详细注释、解题思路、复杂度分析）；💬 注释模式：输入 Python 代码，自动添加详细中。它将相关步骤、

下载

给 serializers.CharField(help_text="用户手机号") 显式加 help_text
对非标准动作（比如 @action(methods=['post'], detail=False)），必须用 @extend_schema(request=YourSerializer, responses={200: YourResponseSerializer}) 手动标注
如果视图方法返回的是原始字典而非 serializer 实例，Swagger 无法自动推导结构，必须用 @extend_schema(responses={200: OpenApiTypes.OBJECT}) 或具体 schema

认证和权限信息不出现？补全 AUTHENTICATION_CLASSES 配置

Swagger UI 默认不会显示认证方式，除非你告诉它有哪些。常见坑是只配了 TokenAuthentication 却没在 schema 设置里声明：

在 settings.py 加：SPECTACULAR_SETTINGS = {'SWAGGER_UI_AUTH_ACTIONS': {'ApiKeyAuth': {'type': 'apiKey', 'in': 'header', 'name': 'Authorization'}}}
更稳妥的做法是在 SPECTACULAR_SETTINGS 中显式设置 'SECURITY_DEFINITIONS'，例如：'Bearer': {'type': 'http', 'scheme': 'bearer', 'bearerFormat': 'JWT'}
如果用了自定义 permission 类且依赖 request header，记得在 @extend_schema 的 security 参数里声明，否则 UI 不会自动带 Authorization 输入框

真正麻烦的不是生成文档，而是让每个 endpoint 的请求参数、响应结构、错误码都真实反映代码逻辑。很多人跑通首页就以为完成了，结果点开一个接口发现 body 是 {}、response 是 object——那基本等于没文档。花十分钟补全 help_text 和 @extend_schema，比后期靠人工写 wiki 强十倍。