应使用 drf-spectacular 而非 coreapi 或旧版 swagger-ui，因其对 drf 3.12+ 支持最佳，零配置即可生成 openapi 3.1 文档；安装需三步：pip install ≥0.27.0、installed_apps 加 'drf_spectacular'、urlconf 挂载 spectacularapiview 和 spectacularswaggerview。
直接用 drf-spectacular，别碰 coreapi 或老版 swagger-ui 集成——它对 Django REST Framework 3.12+ 和 DRF 的 Serializer、APIView、ViewSet、Schema 类型推导最稳，且零配置就能跑出可用文档。
安装与基础配置必须做这三件事
漏掉任一环节都会导致 /api/schema/ 404 或 JSON Schema 空白：
- 运行
pip install drf-spectacular，确认版本 ≥ 0.27.0（低于此版本不支持 OpenAPI 3.1） - 在
INSTALLED_APPS中添加'drf_spectacular'（注意下划线，不是短横线） - 在 URLconf 中显式挂载 schema view：
from drf_spectacular.views import SpectacularAPIView, SpectacularSwaggerView<br><br>urlpatterns = [<br> path('api/schema/', SpectacularAPIView.as_view(), name='schema'),<br> path('api/docs/', SpectacularSwaggerView.as_view(url_name='schema'), name='swagger-ui'),<br> # ... 其他路由<br>]
为什么你的视图没出现在 Swagger 里？检查这四个常见原因
drf-spectacular 默认只扫描带 APIView 子类或 ViewSet 的类视图，函数视图（@api_view）需手动标注；另外它会跳过未启用的视图：
- 函数视图必须加
@extend_schema装饰器，哪怕只写@extend_schema(description="xxx")才会被收录 -
ViewSet的action方法如果用了@action(detail=False, methods=['post'])，但没设url_path，可能被忽略——建议显式加@extend_schema - 视图类设置了
authentication_classes = []且没配permission_classes，有时触发权限校验逻辑导致 schema 提取失败 - URL pattern 用了正则或复杂命名组（如
path('items/<pk>/export/<format>/', ...)</format></pk>），确保format参数在 serializer 或@extend_schema的parameters中声明类型
Serializer 字段注释和 extend_schema 怎么配合才不丢信息
字段描述不会自动从 docstring 或 help_text 提取，必须显式传入——否则 Swagger 里只显示 string 或 integer，没说明：
- 在
Serializer字段定义时用help_text是无效的；正确做法是用description参数：class UserSerializer(serializers.Serializer):<br> email = serializers.EmailField(description="用户注册邮箱，不可重复")<br> avatar = serializers.ImageField(required=False, description="头像图片文件，支持 JPG/PNG")
- 对整个视图定制响应结构，用
@extend_schema(responses={200: UserSerializer})；若返回的是Response(serializer.data)但没指定 status，drf-spectacular可能默认只生成 200，漏掉 400/401 示例 - 如果接口有多个不同结构的响应（如分页 vs 单条），不要只写一个
responses，改用@extend_schema(responses={200: inline_serializer(...), 404: OpenApiResponse(description="未找到")})
真正麻烦的是嵌套 Serializer 和泛型关系（比如 GenericForeignKey），它们的 schema 推导容易出错，这时必须用 @extend_schema_serializer 显式控制字段行为——别指望自动识别。
大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！
