FastAPI 新手入门第 8 篇：让 /docs 更像一份 API 文档

上一篇我们用APIRouter把接口拆到了不同文件里。代码变清楚了，但打开/docs时，接口还是一排排堆在那里。

这一篇我想把/docs往前再推一步：给接口分组，加上简短说明。做完后，items、users、system会分开显示，点开接口时也能知道这个接口用来做什么。

先把接口分组

现在项目里有三个路由文件：

app/routers/ items.py users.py health.py

我希望/docs里也按这三类来展示。最小改动是在APIRouter上加tags。

items.py只看这一行：

fromfastapiimportAPIRouter router=APIRouter(prefix="/items",tags=["items"])

这里顺手把prefix="/items"也放到了路由上。这样文件里的接口就不用反复写/items：

@router.get("",response_model=list[ItemPublic])deflist_items():...@router.get("/{item_id}",response_model=ItemPublic)defread_item(item_id:int):...

最后生成的路径仍然是：

GET /items GET /items/{item_id}

只是/items这段公共路径被放到了APIRouter上。

users.py也一样：

router=APIRouter(prefix="/users",tags=["users"])

health.py不需要路径前缀，只加分组：

router=APIRouter(tags=["system"])

保存后重启服务，打开：

http://127.0.0.1:8000/docs

这时接口会按items、users、system分开。读接口的人不用从一长串列表里猜哪些接口属于同一块。

给接口加一句说明

分组解决的是“接口放在哪里”。点开接口后，还要让人知道“这个接口干什么”。

FastAPI 的路径操作可以直接加summary和description：

@router.get("/{item_id}",response_model=ItemPublic,summary="获取单个商品",description="根据商品 ID 查询商品。商品不存在时返回 404。",)defread_item(item_id:int,token:str=Depends(get_token_header)):ifitem_idnotinfake_items_db:raiseHTTPException(status_code=404,detail="Item not found")returnfake_items_db[item_id]

重点看summary和description。summary是接口列表里那句短说明，description是点开接口后展示的详细说明。

我会把summary写短，把description写成读者能直接用的信息。比如“不存在时返回 404”比“用于查询商品资源”更有用。

POST /items也加上说明：

@router.post("",response_model=ItemPublic,summary="创建商品",description="接收创建商品需要的字段，服务端会补上 ID 和内部字段。",)defcreate_item(item:ItemCreate,token:str=Depends(get_token_header)):...

这句说明也给后面的第 10 篇埋了一个点：创建请求里只传业务输入，服务端会补一些内部字段，但响应里不会全部暴露。

给分组本身加说明

接口能分组之后，还可以给每个分组加说明。这部分放在main.py里：

openapi_tags=[{"name":"items","description":"商品相关接口，用来练习列表、查询和创建。",},{"name":"users","description":"用户相关接口，目前只保留最小查询示例。",},{"name":"system","description":"系统状态接口，用来检查服务是否正常。",},]app=FastAPI(title="FastAPI Beginner Lab",openapi_tags=openapi_tags,)

openapi_tags里的name要和前面tags=["items"]里的名字一致。名字对上后，/docs才知道这段说明属于哪个分组。

刷新/docs，每个分组下面会出现对应描述。

/docs不是给别人看的摆设

我以前刚接触自动文档时，会把它当成“框架附赠的页面”。写一段时间后才发现，/docs对新手最有用的地方不是好看，而是能帮我们确认三件事：

• 路径有没有挂上去：接口没出现在/docs，大概率是路由没注册。
• 参数有没有被识别：请求头、查询参数、请求体会直接显示出来。
• 返回结构是否符合预期：响应模型会影响文档里的响应说明。

所以我会在每次改路由后打开/docs看一眼。它不是最终给产品经理看的完整接口文档，但在开发阶段很省事。

动手改一下

给/health接口加上summary，并把它放进system分组。

app/routers/health.py可以这样写：

fromfastapiimportAPIRouter router=APIRouter(tags=["system"])@router.get("/health",summary="查看服务状态",description="返回服务是否可用。",)defhealth_check():return{"status":"ok"}

保存后刷新/docs。如果/health出现在system分组里，并且点开后能看到“查看服务状态”，这篇就算学完。

到这里，这篇的目标已经完成：

• 我们用tags把接口按items、users、system分组。
• 我们用summary和description给接口补了说明。
• 我们知道了/docs可以用来检查路由、参数和响应结构。

本文代码：https://github.com/tanghaojin/fastapi-beginner-lab/tree/article-08-docs-metadata

下一篇解决另一个问题：配置不要写死在代码里，用环境变量来管理项目配置。

参考资料

• FastAPI Metadata and Docs URLs: https://fastapi.tiangolo.com/tutorial/metadata/
• FastAPI Path Operation Configuration: https://fastapi.tiangolo.com/tutorial/path-operation-configuration/