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

上一篇我们用APIRouter把接口拆到了不同文件里。代码变清楚了但打开/docs时接口还是一排排堆在那里。这一篇我想把/docs往前再推一步给接口分组加上简短说明。做完后items、users、system会分开显示点开接口时也能知道这个接口用来做什么。先把接口分组现在项目里有三个路由文件app/routers/ items.py users.py health.py我希望/docs里也按这三类来展示。最小改动是在APIRouter上加tags。items.py只看这一行fromfastapiimportAPIRouter routerAPIRouter(prefix/items,tags[items])这里顺手把prefix/items也放到了路由上。这样文件里的接口就不用反复写/itemsrouter.get(,response_modellist[ItemPublic])deflist_items():...router.get(/{item_id},response_modelItemPublic)defread_item(item_id:int):...最后生成的路径仍然是GET /items GET /items/{item_id}只是/items这段公共路径被放到了APIRouter上。users.py也一样routerAPIRouter(prefix/users,tags[users])health.py不需要路径前缀只加分组routerAPIRouter(tags[system])保存后重启服务打开http://127.0.0.1:8000/docs这时接口会按items、users、system分开。读接口的人不用从一长串列表里猜哪些接口属于同一块。给接口加一句说明分组解决的是“接口放在哪里”。点开接口后还要让人知道“这个接口干什么”。FastAPI 的路径操作可以直接加summary和descriptionrouter.get(/{item_id},response_modelItemPublic,summary获取单个商品,description根据商品 ID 查询商品。商品不存在时返回 404。,)defread_item(item_id:int,token:strDepends(get_token_header)):ifitem_idnotinfake_items_db:raiseHTTPException(status_code404,detailItem not found)returnfake_items_db[item_id]重点看summary和description。summary是接口列表里那句短说明description是点开接口后展示的详细说明。我会把summary写短把description写成读者能直接用的信息。比如“不存在时返回 404”比“用于查询商品资源”更有用。POST /items也加上说明router.post(,response_modelItemPublic,summary创建商品,description接收创建商品需要的字段服务端会补上 ID 和内部字段。,)defcreate_item(item:ItemCreate,token:strDepends(get_token_header)):...这句说明也给后面的第 10 篇埋了一个点创建请求里只传业务输入服务端会补一些内部字段但响应里不会全部暴露。给分组本身加说明接口能分组之后还可以给每个分组加说明。这部分放在main.py里openapi_tags[{name:items,description:商品相关接口用来练习列表、查询和创建。,},{name:users,description:用户相关接口目前只保留最小查询示例。,},{name:system,description:系统状态接口用来检查服务是否正常。,},]appFastAPI(titleFastAPI Beginner Lab,openapi_tagsopenapi_tags,)openapi_tags里的name要和前面tags[items]里的名字一致。名字对上后/docs才知道这段说明属于哪个分组。刷新/docs每个分组下面会出现对应描述。/docs不是给别人看的摆设我以前刚接触自动文档时会把它当成“框架附赠的页面”。写一段时间后才发现/docs对新手最有用的地方不是好看而是能帮我们确认三件事路径有没有挂上去接口没出现在/docs大概率是路由没注册。参数有没有被识别请求头、查询参数、请求体会直接显示出来。返回结构是否符合预期响应模型会影响文档里的响应说明。所以我会在每次改路由后打开/docs看一眼。它不是最终给产品经理看的完整接口文档但在开发阶段很省事。动手改一下给/health接口加上summary并把它放进system分组。app/routers/health.py可以这样写fromfastapiimportAPIRouter routerAPIRouter(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/