直接用 drf-yasg 是因 DRF 原生不支持 OpenAPI 3.0，coreapi 已弃用且仅支持 2.0，而 drf-yasg 稳定适配 DRF 3.12+ 并默认生成 OpenAPI 3.0，能自动提取视图与序列化器字段。
为什么直接用 drf-yasg 而不是 coreapi 或 swagger-ui-py？
因为 Django REST Framework（DRF）原生不输出 OpenAPI 3.0 规范，coreapi 已弃用且只支持 OpenAPI 2.0，而 drf-yasg 是目前最稳定、适配 DRF 3.12+ 且默认生成 OpenAPI 3.0 的方案。它能自动从 @api_view、APIView、ViewSet 和 serializer 中提取字段，不用手写 swagger_auto_schema——除非你有特殊字段需要覆盖。
安装与基础配置三步走
别跳过中间的 SWAGGER_SETTINGS 配置，否则会出现“Try it out”按钮禁用、鉴权头不自动带、模型定义缺失等问题。
- 运行
pip install drf-yasg，然后在INSTALLED_APPS加入'drf_yasg' - 在主
urls.py中添加路由：from drf_yasg.views import get_schema_view<br>from drf_yasg import openapi<br><br>schema_view = get_schema_view(<br> openapi.Info(title="API", default_version='v1'),<br> public=True,<br>)<br>urlpatterns += [<br> path('swagger/', schema_view.with_ui('swagger', cache_timeout=0), name='schema-swagger-ui'),<br>] - 补上关键配置项（放在
settings.py）：SWAGGER_SETTINGS = {<br> 'SECURITY_DEFINITIONS': {<br> 'Bearer': {<br> 'type': 'apiKey',<br> 'name': 'Authorization',<br> 'in': 'header'<br> }<br> },<br> 'DEFAULT_MODEL_RENDERING': 'example',<br> 'USE_SESSION_AUTH': False,<br>}
如何让 ViewSet 的 list/retrieve 等动作正确显示参数和响应？
drf-yasg 默认能识别 get_serializer_class() 和 get_queryset()，但对 URL path 参数（如 /users/{id}/）和 query 参数（如 ?page=1）不会自动标注——必须显式声明。
提供使用 django-unfold (v0.56+) 构建高级 Django 管理界面的专业指导。当用户提及 django-unfold、unfold admin 等内容时使用此技能。
- 路径参数要用
path_parameter：在retrieve方法上加装饰器@swagger_auto_schema(operation_description="获取单个用户", manual_parameters=[openapi.Parameter('id', openapi.IN_PATH, type=openapi.TYPE_INTEGER)]) - query 参数建议统一用
ManualParameter列表传给@swagger_auto_schema，而不是依赖 DRF 的pagination_class自动推导（它常漏掉limit、offset等自定义分页参数） - 响应体若返回非 serializer 数据（比如
Response({'count': 10})），必须用responses参数指定：@swagger_auto_schema(responses={200: openapi.Response('统计结果', openapi.Schema(type=openapi.TYPE_OBJECT, properties={'count': openapi.Schema(type=openapi.TYPE_INTEGER)}))})
常见报错和绕过方式
最常卡在 AssertionError: Serializer class ... is not valid 或 Swagger UI 显示 “Failed to load API definition” —— 通常不是 YAML 格式问题，而是 serializer 引用了未注册的 model 字段或动态 SerializerMethodField 返回了不可序列化的对象。
立即学习“Python免费学习笔记（深入）”；
- 检查所有
SerializerMethodField方法是否都加了@swagger_serializer_method装饰器，并返回明确类型（如openapi.TYPE_STRING） - 避免在 serializer 中使用
models.ForeignKey直接作为字段，改用PrimaryKeyRelatedField或显式定义to_representation - 如果用了
GenericAPIView+get_serializer动态返回不同 serializer，drf-yasg会无法推断——此时必须用query_serializer和request_body显式指定 - 调试时访问
/swagger/?format=openapi查看原始 YAML，比 UI 报错更早暴露$ref循环引用或 missing definition 问题
真正麻烦的不是生成文档，而是让每个 endpoint 的 request/response 和实际行为完全对齐；一旦 serializer 和 view logic 出现分支逻辑，Swagger 就只能靠人工 patch。
