drf-spectacular是目前最省心、兼容性最好、真正开箱即用的DRF OpenAPI文档方案，需安装配置、补全serializer注释及@extend_schema标注、显式声明认证与安全定义。
用 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 空白，大概率是这些地方没填：
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 设置里声明：
立即学习“Python免费学习笔记（深入）”；
- 在
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 强十倍。
