FastAPI默认自动生成符合OpenAPI规范的文档，无需额外配置；空白或404因docs_url=None、反向代理未透传路径、/docs被mount覆盖，响应模型需显式声明response_model。
FastAPI 默认就生成符合 OpenAPI 规范的文档，不需要额外配置——只要你的路由函数有类型注解、参数有 Query/Path/Body 等声明，它就能自动推导出完整的 openapi.json 和交互式 UI。
为什么 /docs 页面空白或报 404？
这是最常见的“没文档”错觉，实际是服务未启用文档端点或路径被覆盖：
- 确认没调用
app = FastAPI(docs_url=None)或docs_url=""—— 这会显式禁用文档 - 检查是否在反向代理（如 Nginx）后运行，且未正确透传
/docs和/openapi.json路径 - 若用了
app.mount()挂载静态文件，确保没把/docs路径覆盖成其他 handler - 开发时直接访问
http://localhost:8000/docs，不是/doc或/swagger
Response 模型不显示在文档中？
FastAPI 只对 response_model 参数指定的模型生成响应结构，仅靠 return 值的类型注解无效：
- 必须显式写
@app.get("/items", response_model=Item)，不能只写def read_item() -> Item: - 若返回
List[Item]，需用response_model=list[Item]（Python 3.9+）或response_model=List[Item]（需from typing import List） - 使用
Union多类型响应时，要配合response_model和response_model_exclude_unset=True控制字段可见性
如何让 openapi.json 包含服务器地址和认证信息？
默认生成的 OpenAPI JSON 不带 servers 和 components.securitySchemes，需手动注入：
立即学习“Python免费学习笔记（深入）”；
- 通过
FastAPI初始化参数添加基础信息：app = FastAPI(servers=[{"url": "https://api.example.com/v1"}]) - JWT 认证需定义
OAuth2PasswordBearer实例并传入依赖，FastAPI 才会在components.securitySchemes中生成对应结构 - 自定义字段描述要用
Field(..., description="...")，而非 docstring；模型 docstring 仅用于模块级说明，不进 OpenAPI - 若用
include_router()，确保子路由的tags参数已设，否则接口会归到 “default” 分组，影响 UI 分类
OpenAPI 文档的准确性完全依赖你写的类型注解和声明方式，而不是运行时行为。一个没加 response_model 的 POST 接口，即使返回了字典，文档里也只会标 200: {}——这点容易被忽略，直到前端开始抱怨“看不到返回字段”。
