FastAPI 默认提供 Swagger UI（/docs）和 OpenAPI JSON（/openapi.json），通过类型注解与 Pydantic 模型自动推导接口文档；常见问题包括404（启动错误、路径被代理截断、docs_url=None）、请求体不显示（模型未继承BaseModel或类型缺失）、定制需用title/description/servers/version参数；生产环境禁用文档应谨慎，仅设docs_url=None仍暴露/openapi.json，彻底禁用需同时设openapi_url=None或加访问控制。
FastAPI 默认就生成 Swagger UI，不用额外配置
只要你的 FastAPI 应用跑起来，默认 /docs 路径就是可交互的 Swagger UI 页面，背后是自动生成的 OpenAPI JSON（在 /openapi.json）。这不依赖你手动写文档，而是靠类型注解 + Pydantic 模型自动推导出请求体、响应结构、状态码、参数位置等。
常见错误现象：404 Not Found 访问 /docs —— 大概率是开发服务器没启对，或用了 uvicorn.run() 但没传 debug=True（虽然不影响文档生成，但新手常误以为关了调试就关了文档）；也可能是反向代理（如 Nginx）把 /docs 路径截断或重写了。
- 确保启动命令类似
uvicorn main:app --reload，且main.py中的app = FastAPI()实例没被条件包裹（比如没放在if __name__ == "__main__":里却没运行） - 检查是否显式设置了
docs_url=None或redoc_url=None—— 这会直接禁用对应界面 - 如果部署在子路径（如
/api/docs），需配置app = FastAPI(docs_url="/api/docs")并同步处理静态资源路由
接口文档不显示请求体或 422 错误？检查 Pydantic 模型和类型注解
Swagger 文档里「Request Body」为空、或 POST 接口点开后只有 application/json 却没字段定义，通常不是 FastAPI 的问题，而是模型没被正确引用或类型缺失。
使用场景：你写了 def create_item(item: Item)，但 Item 是普通 dict 或没继承 BaseModel；或者用了 Union / Optional 却没给默认值，导致 FastAPI 无法判断是否必需。
立即学习“Python免费学习笔记（深入）”；
-
Item必须是Pydantic.BaseModel子类，不能是dict、dataclass（除非显式加@pydantic.dataclasses.dataclass） - 路径参数、查询参数、请求体必须用明确类型注解，比如
user_id: int，不能只写user_id - 避免在依赖函数里返回裸字典——如果依赖需要参与文档生成（比如作为请求体一部分），也得包装成
BaseModel
示例：
from pydantic import BaseModel<br><br>class Item(BaseModel):<br> name: str<br> price: float<br><br>@app.post("/items/")<br>def create_item(item: Item): # ← 这里 item 类型触发自动文档生成<br> return item
如何定制 Swagger UI 的标题、描述、服务器地址
OpenAPI 的元信息（比如页面左上角的标题、description、默认请求的 servers 列表）由 FastAPI 初始化参数控制，不是靠中间件或模板文件。
性能 / 兼容性影响：这些只是 JSON 字段，不增加运行时开销，但改错 servers 可能导致你在 UI 里点「Try it out」时发到错误域名。
- 标题和描述用
title和description参数：app = FastAPI(title="My API", description="Handles user and item ops") - 指定请求目标服务器（影响 UI 中下拉选择）：
servers=[{"url": "https://api.example.com/v1", "description": "Production"}] - 版本号由
version参数控制，默认是"0.1.0"；它会出现在 OpenAPI JSON 的info.version字段，Swagger UI 通常显示在右下角
生产环境禁用文档？别只关 /docs
设 docs_url=None 确实隐藏了 Swagger UI，但 /openapi.json 依然可访问——只要这个 JSON 在，第三方工具（比如 Postman、curl、自动化测试脚本）就能还原全部接口。真要限制，得一并处理 OpenAPI endpoint。
容易踩的坑：有人以为关掉 UI 就“安全”了，结果扫描器扫到 /openapi.json，直接拿到所有接口定义和示例 payload。
- 彻底禁用：
app = FastAPI(docs_url=None, openapi_url=None)—— 但这样连健康检查、监控集成都可能受影响 - 更稳妥的做法是保留
openapi_url，但用中间件按 IP 或 Header 控制访问，例如只允许内网或带特定 token 的请求 - 注意：禁用后，
fastapi.openapi.docs.get_swagger_ui_html等函数调用会失败，别在代码里硬编码引用它们
复杂点在于，文档开关和权限控制是两层事——UI 是前端展示，OpenAPI JSON 是机器可读契约，很多内部系统依赖后者做自动化对接。关哪个、怎么关，得看实际协作边界在哪。
