交互式文档

FastAPI 会根据你的代码自动生成 OpenAPI 文档，并提供两个浏览器页面。

启动项目：

fastapi dev main.py

然后访问：

地址	作用
`http://127.0.0.1:8000/docs`	Swagger UI，最常用，可直接调试接口
`http://127.0.0.1:8000/redoc`	ReDoc，适合阅读接口说明
`http://127.0.0.1:8000/openapi.json`	原始 OpenAPI JSON

一、给应用加标题

from fastapi import FastAPI

app = FastAPI(
    title="用户系统 API",
    description="这是一个学习 FastAPI 的示例项目",
    version="0.1.0",
)

刷新 /docs 后，页面顶部会显示这些信息。

二、给接口分组

用 tags 给接口分组：

@app.get("/", tags=["基础"])
def root():
    return {"message": "Hello FastAPI"}


@app.get("/users/", tags=["用户"])
def list_users():
    return [{"id": 1, "name": "张三"}]

在 /docs 里，接口会按标签折叠展示。

三、给接口加说明

@app.get(
    "/users/{user_id}",
    tags=["用户"],
    summary="查询单个用户",
    description="根据用户 ID 查询用户基础信息。",
)
def get_user(user_id: int):
    return {"id": user_id, "name": "张三"}

常用参数：

参数	作用
`tags`	接口分组
`summary`	接口一句话说明
`description`	更详细的说明
`response_model`	响应数据结构，后面会讲
`status_code`	成功响应状态码

四、直接在文档里测试

访问 /docs 后：

展开一个接口。
点击 Try it out。
填写参数。
点击 Execute。
查看请求地址、响应状态码和响应 JSON。

这对初学者很重要，因为你不用先学 Postman、curl 或前端请求，就能直接调试后端接口。

五、文档从哪里来

FastAPI 主要从这些信息生成文档：

代码信息	文档效果
路由地址	显示接口路径
HTTP 方法	显示 `GET`、`POST` 等方法
类型注解	显示参数类型并自动校验
Pydantic 模型	显示请求体和响应体结构
`summary` / `description`	显示接口说明

所以，FastAPI 里类型注解不是摆设。写清楚类型，代码更安全，文档也更完整。

#交互式文档

#一、给应用加标题

#二、给接口分组

#三、给接口加说明

#四、直接在文档里测试