FastAPIPath Operation Decorator 配置全指南——status_code、tags、summary、description 与 deprecated 元数据【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi本指南聚焦 FastAPI 中**路径操作装饰器path operation decorator**的配置能力如何通过向app.get()、app.post()等装饰器传入参数为每个 API 端点声明响应状态码、分组标签、标题与描述文本以及标记弃用接口。阅读完本文你将掌握一套直接作用于 OpenAPI 模式与自动交互式文档的元数据配置方法让生成的 Swagger UI / ReDoc 文档与团队规范无缝对齐。全文示例均取自本仓库 docs_src/path_operation_configuration/ 目录示例要求 Python 3.10代码中使用str | None联合类型语法并可在本仓库 tests 目录中找到对应回归测试。关键前提参数属于装饰器而非函数所有配置参数都直接传给 path operation decorator而不是传给被装饰的path operation function。即它们书写在app.get(...)/app.post(...)的括号里而不是在async def ...的函数签名里。Advertencia警告这些参数是传给 path operation decorator 的不是传给 path operation function 的。写错位置时这些参数不会生效。从源码实现看这些参数最终会汇聚到 fastapi/routing.py 的路由注册逻辑中装饰器在底层通过APIRouter.add_api_route(...)构建APIRoute实例并把tags、deprecated、response_description等元数据记录到路由对象上随后在生成 OpenAPI 模式时被读取对应response_description: str Successful Response、deprecated: bool | None None、tags: list[str | Enum] | None None等默认签名见 fastapi/routing.py。以下示例共用同一个Item请求体模型from fastapi import FastAPI from pydantic import BaseModel app FastAPI() class Item(BaseModel): name: str description: str | None None price: float tax: float | None None tags: set[str] set()配置响应状态码status_code可以通过status_code参数指定 path operation 响应所使用的 HTTP 状态码它会实际用于 HTTP response同时也会被加入 OpenAPI 模式responses字段。可以直接传数字int例如404如果记不住每个数字对应的语义可以使用status模块中的快捷常量from fastapi import FastAPI, status from pydantic import BaseModel app FastAPI() class Item(BaseModel): name: str description: str | None None price: float tax: float | None None tags: set[str] set() app.post(/items/, status_codestatus.HTTP_201_CREATED) async def create_item(item: Item) - Item: return item完整代码见 tutorial001_py310.py上例把 POST/items/的响应状态码设为201 Created比默认的 200 更贴合「资源创建成功」的语义。对应的回归测试 test_tutorial001.py 同时验证了两件事其一真实响应状态码确实是 201assert response.status_code 201其二通过client.get(/openapi.json)得到的模式中paths[/items/][post][responses]下挂着201键而非200证明该状态码同时写入了 OpenAPI schema。Nota técnica技术细节你也可以使用from starlette import status。FastAPI只是出于开发者便利把同一个starlette.status再以fastapi.status的形式导出它的源头就是 Starlette 模块。这意味着两者是同一组常量fastapi.status.HTTP_201_CREATED与starlette.status.HTTP_201_CREATED指向同一个值按项目风格二选一即可。添加分组标签tagstags参数接受一个str组成的list实践中常常只有一个字符串。FastAPI 会把 tags 写入 OpenAPI 模式交互式文档则据此把路径按标签分组展示from fastapi import FastAPI from pydantic import BaseModel app FastAPI() class Item(BaseModel): name: str description: str | None None price: float tax: float | None None tags: set[str] set() app.post(/items/, tags[items]) async def create_item(item: Item) - Item: return item app.get(/items/, tags[items]) async def read_items(): return [{name: Foo, price: 42}] app.get(/users/, tags[users]) async def read_users(): return [{username: johndoe}]完整代码见 tutorial002_py310.py上面create_item与read_items都标记了itemsread_users标记usersSwagger UI 中/items/相关的 GET/POST 路径就会聚合到items分组下/users/路径则单独归入users分组对应测试见 test_tutorial002.py其中会断言 OpenAPI 模式的 tags 列表与分组结果。用 Enum 管理 tags避免拼写漂移在大型应用中路径操作会越来越多tags 也会越积越多。若全靠手写字符串很容易在多个相关接口上出现items与item之类的拼写不一致导致文档分组混乱。此时把 tags 集中存放进一个Enum是更稳妥的做法FastAPI 对Enum的支持与普通字符串完全相同from enum import Enum from fastapi import FastAPI app FastAPI() class Tags(Enum): items items users users app.get(/items/, tags[Tags.items]) async def get_items(): return [Portal gun, Plumbus] app.get(/users/, tags[Tags.users]) async def read_users(): return [Rick, Morty]完整代码见 tutorial002b_py310.pyTags枚举集中定义了所有合法标签声明路由时写tags[Tags.items]即可。从 fastapi/routing.py 的类型签名也能印证这一点tags: list[str | Enum]即列表元素既可以是str也可以是Enum成员。这样一来「同一组相关接口始终使用同一个标签」由类型系统与集中定义来保证而不是依赖每个开发者的记忆。注意传参时仍要放在list里如tags[Tags.items]。对应测试见 test_tutorial002b.py。添加 summary 与 description 元数据summary是路径操作在图示文档中显示的短标题description则用于承载更长的说明文字from fastapi import FastAPI from pydantic import BaseModel app FastAPI() class Item(BaseModel): name: str description: str | None None price: float tax: float | None None tags: set[str] set() app.post( /items/, summaryCreate an item, descriptionCreate an item with all the information, name, description, price, tax and a set of unique tags, ) async def create_item(item: Item) - Item: return item完整代码见 tutorial003_py310.pysummary通常保持简洁类似文档标题description可写成较长的单行字符串也可以继续用「从 docstring 读取描述」的方式承载多行文本。用 docstring 承载长描述并支持 Markdown由于接口描述往往很长、需要跨越多行直接在装饰器参数里写会非常臃肿。FastAPI 的解决方案是把描述写进 path operation function 的docstring函数体内的首条多行字符串表达式FastAPI 会自动读取它并当作description使用。docstring 里可以书写Markdown会被正确解释渲染渲染时会正确处理 docstring 的缩进from fastapi import FastAPI from pydantic import BaseModel app FastAPI() class Item(BaseModel): name: str description: str | None None price: float tax: float | None None tags: set[str] set() app.post(/items/, summaryCreate an item) async def create_item(item: Item) - Item: Create an item with all the information: - **name**: each item must have a name - **description**: a long description - **price**: required - **tax**: if the item doesnt have tax, you can omit this - **tags**: a set of unique tag strings for this item return item完整代码见 tutorial004_py310.py注意上例只显式传了summarydescription完全来自 docstring。docstring 中的 Markdown 列表、粗体、行内代码等语法都会在交互式文档中按语义渲染测试层面test_tutorial003_tutorial004.py 对 tutorial003 与 tutorial004 做了对照断言两个示例产生的 OpenAPI 模式中paths[/items/][post][summary]都是Create an item而description字段分别取自「装饰器显式传入的字符串」与「docstring经textwrap.dedent去除公共缩进后的文本」二者殊途同归最终都进入 OpenAPI 模式。单独声明响应描述response_descriptionresponse_description参数用于指定**响应response**的描述文字它出现在交互式文档每个状态码条目下from fastapi import FastAPI from pydantic import BaseModel app FastAPI() class Item(BaseModel): name: str description: str | None None price: float tax: float | None None tags: set[str] set() app.post( /items/, summaryCreate an item, response_descriptionThe created item, ) async def create_item(item: Item) - Item: Create an item with all the information: - **name**: each item must have a name - **description**: a long description - **price**: required - **tax**: if the item doesnt have tax, you can omit this - **tags**: a set of unique tag strings for this item return item完整代码见 tutorial005_py310.pyNota注意response_description专门描述 response而description描述的是整个 path operation两者指向不同的 OpenAPI 字段不要混淆。Consejo提示OpenAPI 规范要求每个 path operation 都必须有 response description。因此如果你没有显式提供FastAPI 会自动生成默认值Successful Response。这一点同样能从 fastapi/routing.py 的签名默认值response_description: str Successful Response得到印证。设置response_descriptionThe created item后交互式文档中200状态码条目下方的说明就显示为The created item同时文档仍会展示由 Pydantic 模型自动推导的响应体结构与422 Validation Error校验失败结构标记弃用接口deprecated当接口需要被标记为已弃用obsolete官方不推荐继续使用但又不能立即删除时给装饰器传deprecatedTrue即可。该参数在交互式文档中会明确标注 deprecated同时接口仍可正常调用from fastapi import FastAPI app FastAPI() app.get(/items/, tags[items]) async def read_items(): return [{name: Foo, price: 42}] app.get(/users/, tags[users]) async def read_users(): return [{username: johndoe}] app.get(/elements/, tags[items], deprecatedTrue) async def read_elements(): return [{item_id: Foo}]完整代码见 tutorial006_py310.py以deprecatedTrue标记的/elements/路径会在交互式文档中呈现为灰色弱化样式并显示Warning: Deprecated提示让使用方包括人类与代码生成客户端明确得知该接口已不推荐使用把弃用与未弃用的路径操作放在一起对比灰色弱化与正常高亮的区别非常直观客户端生成工具也可依据 OpenAPI 中deprecated: true字段自动处理对应的 test_tutorial006.py 会断言 OpenAPI 模式中/elements/的 GET 操作带上了deprecated: true。在 fastapi/routing.py 中该参数的类型为deprecated: bool | None None即默认不弃用传入True时才生效。各配置参数一览把上文参数汇总如下均作为 path operation decorator 的命名参数传入参数类型默认行为作用与落点status_codeint200设定实际 HTTP 响应状态码并写入 OpenAPIresponsestagslist[str | Enum]None无分组供 OpenAPI 与交互式文档对路径分组summarystr由函数名推断path operation 的短标题OpenAPIsummarydescriptionstr缺省时读取函数 docstringpath operation 的完整描述OpenAPIdescriptionresponse_descriptionstrSuccessful Responseresponse 的描述OpenAPIresponses.code.descriptiondeprecatedboolFalse标记接口弃用OpenAPIdeprecated: true总结FastAPI 允许通过给path operation decorator传参非常轻量地为接口附加丰富的配置与元数据status_code控制响应状态码与文档一致性tags含 Enum 化管理驱动文档分组summary/description/ docstring支持 Markdown定义标题与详述response_description细化响应说明deprecated无痛标记退役接口。这些配置最终都汇入 OpenAPI 模式可访问/openapi.json查看使自动生成的文档、SDK 与文档界面的信息质量完全由几行装饰器参数掌控。如果想继续深入可以阅读本教程的英文原版与配套代码 tutorial 目录源码在本仓库运行对应回归测试验证各参数生成的 OpenAPI 模式测试目录为 tests/test_tutorial/test_path_operation_configurations/结合 fastapi/routing.py 中APIRoute与add_api_route的签名理解参数流向在搭建大型 API 项目时还可以参考本仓库中关于 Python 类型注解、请求体与响应模型等进阶教程把元数据配置与类型驱动的校验能力组合起来。【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 FastAPI：Path Operation Decorator 配置全指南——status_code、tags、summary、description 与 deprecated 元数据
FastAPIPath Operation Decorator 配置全指南——status_code、tags、summary、description 与 deprecated 元数据【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi本指南聚焦 FastAPI 中**路径操作装饰器path operation decorator**的配置能力如何通过向app.get()、app.post()等装饰器传入参数为每个 API 端点声明响应状态码、分组标签、标题与描述文本以及标记弃用接口。阅读完本文你将掌握一套直接作用于 OpenAPI 模式与自动交互式文档的元数据配置方法让生成的 Swagger UI / ReDoc 文档与团队规范无缝对齐。全文示例均取自本仓库 docs_src/path_operation_configuration/ 目录示例要求 Python 3.10代码中使用str | None联合类型语法并可在本仓库 tests 目录中找到对应回归测试。关键前提参数属于装饰器而非函数所有配置参数都直接传给 path operation decorator而不是传给被装饰的path operation function。即它们书写在app.get(...)/app.post(...)的括号里而不是在async def ...的函数签名里。Advertencia警告这些参数是传给 path operation decorator 的不是传给 path operation function 的。写错位置时这些参数不会生效。从源码实现看这些参数最终会汇聚到 fastapi/routing.py 的路由注册逻辑中装饰器在底层通过APIRouter.add_api_route(...)构建APIRoute实例并把tags、deprecated、response_description等元数据记录到路由对象上随后在生成 OpenAPI 模式时被读取对应response_description: str Successful Response、deprecated: bool | None None、tags: list[str | Enum] | None None等默认签名见 fastapi/routing.py。以下示例共用同一个Item请求体模型from fastapi import FastAPI from pydantic import BaseModel app FastAPI() class Item(BaseModel): name: str description: str | None None price: float tax: float | None None tags: set[str] set()配置响应状态码status_code可以通过status_code参数指定 path operation 响应所使用的 HTTP 状态码它会实际用于 HTTP response同时也会被加入 OpenAPI 模式responses字段。可以直接传数字int例如404如果记不住每个数字对应的语义可以使用status模块中的快捷常量from fastapi import FastAPI, status from pydantic import BaseModel app FastAPI() class Item(BaseModel): name: str description: str | None None price: float tax: float | None None tags: set[str] set() app.post(/items/, status_codestatus.HTTP_201_CREATED) async def create_item(item: Item) - Item: return item完整代码见 tutorial001_py310.py上例把 POST/items/的响应状态码设为201 Created比默认的 200 更贴合「资源创建成功」的语义。对应的回归测试 test_tutorial001.py 同时验证了两件事其一真实响应状态码确实是 201assert response.status_code 201其二通过client.get(/openapi.json)得到的模式中paths[/items/][post][responses]下挂着201键而非200证明该状态码同时写入了 OpenAPI schema。Nota técnica技术细节你也可以使用from starlette import status。FastAPI只是出于开发者便利把同一个starlette.status再以fastapi.status的形式导出它的源头就是 Starlette 模块。这意味着两者是同一组常量fastapi.status.HTTP_201_CREATED与starlette.status.HTTP_201_CREATED指向同一个值按项目风格二选一即可。添加分组标签tagstags参数接受一个str组成的list实践中常常只有一个字符串。FastAPI 会把 tags 写入 OpenAPI 模式交互式文档则据此把路径按标签分组展示from fastapi import FastAPI from pydantic import BaseModel app FastAPI() class Item(BaseModel): name: str description: str | None None price: float tax: float | None None tags: set[str] set() app.post(/items/, tags[items]) async def create_item(item: Item) - Item: return item app.get(/items/, tags[items]) async def read_items(): return [{name: Foo, price: 42}] app.get(/users/, tags[users]) async def read_users(): return [{username: johndoe}]完整代码见 tutorial002_py310.py上面create_item与read_items都标记了itemsread_users标记usersSwagger UI 中/items/相关的 GET/POST 路径就会聚合到items分组下/users/路径则单独归入users分组对应测试见 test_tutorial002.py其中会断言 OpenAPI 模式的 tags 列表与分组结果。用 Enum 管理 tags避免拼写漂移在大型应用中路径操作会越来越多tags 也会越积越多。若全靠手写字符串很容易在多个相关接口上出现items与item之类的拼写不一致导致文档分组混乱。此时把 tags 集中存放进一个Enum是更稳妥的做法FastAPI 对Enum的支持与普通字符串完全相同from enum import Enum from fastapi import FastAPI app FastAPI() class Tags(Enum): items items users users app.get(/items/, tags[Tags.items]) async def get_items(): return [Portal gun, Plumbus] app.get(/users/, tags[Tags.users]) async def read_users(): return [Rick, Morty]完整代码见 tutorial002b_py310.pyTags枚举集中定义了所有合法标签声明路由时写tags[Tags.items]即可。从 fastapi/routing.py 的类型签名也能印证这一点tags: list[str | Enum]即列表元素既可以是str也可以是Enum成员。这样一来「同一组相关接口始终使用同一个标签」由类型系统与集中定义来保证而不是依赖每个开发者的记忆。注意传参时仍要放在list里如tags[Tags.items]。对应测试见 test_tutorial002b.py。添加 summary 与 description 元数据summary是路径操作在图示文档中显示的短标题description则用于承载更长的说明文字from fastapi import FastAPI from pydantic import BaseModel app FastAPI() class Item(BaseModel): name: str description: str | None None price: float tax: float | None None tags: set[str] set() app.post( /items/, summaryCreate an item, descriptionCreate an item with all the information, name, description, price, tax and a set of unique tags, ) async def create_item(item: Item) - Item: return item完整代码见 tutorial003_py310.pysummary通常保持简洁类似文档标题description可写成较长的单行字符串也可以继续用「从 docstring 读取描述」的方式承载多行文本。用 docstring 承载长描述并支持 Markdown由于接口描述往往很长、需要跨越多行直接在装饰器参数里写会非常臃肿。FastAPI 的解决方案是把描述写进 path operation function 的docstring函数体内的首条多行字符串表达式FastAPI 会自动读取它并当作description使用。docstring 里可以书写Markdown会被正确解释渲染渲染时会正确处理 docstring 的缩进from fastapi import FastAPI from pydantic import BaseModel app FastAPI() class Item(BaseModel): name: str description: str | None None price: float tax: float | None None tags: set[str] set() app.post(/items/, summaryCreate an item) async def create_item(item: Item) - Item: Create an item with all the information: - **name**: each item must have a name - **description**: a long description - **price**: required - **tax**: if the item doesnt have tax, you can omit this - **tags**: a set of unique tag strings for this item return item完整代码见 tutorial004_py310.py注意上例只显式传了summarydescription完全来自 docstring。docstring 中的 Markdown 列表、粗体、行内代码等语法都会在交互式文档中按语义渲染测试层面test_tutorial003_tutorial004.py 对 tutorial003 与 tutorial004 做了对照断言两个示例产生的 OpenAPI 模式中paths[/items/][post][summary]都是Create an item而description字段分别取自「装饰器显式传入的字符串」与「docstring经textwrap.dedent去除公共缩进后的文本」二者殊途同归最终都进入 OpenAPI 模式。单独声明响应描述response_descriptionresponse_description参数用于指定**响应response**的描述文字它出现在交互式文档每个状态码条目下from fastapi import FastAPI from pydantic import BaseModel app FastAPI() class Item(BaseModel): name: str description: str | None None price: float tax: float | None None tags: set[str] set() app.post( /items/, summaryCreate an item, response_descriptionThe created item, ) async def create_item(item: Item) - Item: Create an item with all the information: - **name**: each item must have a name - **description**: a long description - **price**: required - **tax**: if the item doesnt have tax, you can omit this - **tags**: a set of unique tag strings for this item return item完整代码见 tutorial005_py310.pyNota注意response_description专门描述 response而description描述的是整个 path operation两者指向不同的 OpenAPI 字段不要混淆。Consejo提示OpenAPI 规范要求每个 path operation 都必须有 response description。因此如果你没有显式提供FastAPI 会自动生成默认值Successful Response。这一点同样能从 fastapi/routing.py 的签名默认值response_description: str Successful Response得到印证。设置response_descriptionThe created item后交互式文档中200状态码条目下方的说明就显示为The created item同时文档仍会展示由 Pydantic 模型自动推导的响应体结构与422 Validation Error校验失败结构标记弃用接口deprecated当接口需要被标记为已弃用obsolete官方不推荐继续使用但又不能立即删除时给装饰器传deprecatedTrue即可。该参数在交互式文档中会明确标注 deprecated同时接口仍可正常调用from fastapi import FastAPI app FastAPI() app.get(/items/, tags[items]) async def read_items(): return [{name: Foo, price: 42}] app.get(/users/, tags[users]) async def read_users(): return [{username: johndoe}] app.get(/elements/, tags[items], deprecatedTrue) async def read_elements(): return [{item_id: Foo}]完整代码见 tutorial006_py310.py以deprecatedTrue标记的/elements/路径会在交互式文档中呈现为灰色弱化样式并显示Warning: Deprecated提示让使用方包括人类与代码生成客户端明确得知该接口已不推荐使用把弃用与未弃用的路径操作放在一起对比灰色弱化与正常高亮的区别非常直观客户端生成工具也可依据 OpenAPI 中deprecated: true字段自动处理对应的 test_tutorial006.py 会断言 OpenAPI 模式中/elements/的 GET 操作带上了deprecated: true。在 fastapi/routing.py 中该参数的类型为deprecated: bool | None None即默认不弃用传入True时才生效。各配置参数一览把上文参数汇总如下均作为 path operation decorator 的命名参数传入参数类型默认行为作用与落点status_codeint200设定实际 HTTP 响应状态码并写入 OpenAPIresponsestagslist[str | Enum]None无分组供 OpenAPI 与交互式文档对路径分组summarystr由函数名推断path operation 的短标题OpenAPIsummarydescriptionstr缺省时读取函数 docstringpath operation 的完整描述OpenAPIdescriptionresponse_descriptionstrSuccessful Responseresponse 的描述OpenAPIresponses.code.descriptiondeprecatedboolFalse标记接口弃用OpenAPIdeprecated: true总结FastAPI 允许通过给path operation decorator传参非常轻量地为接口附加丰富的配置与元数据status_code控制响应状态码与文档一致性tags含 Enum 化管理驱动文档分组summary/description/ docstring支持 Markdown定义标题与详述response_description细化响应说明deprecated无痛标记退役接口。这些配置最终都汇入 OpenAPI 模式可访问/openapi.json查看使自动生成的文档、SDK 与文档界面的信息质量完全由几行装饰器参数掌控。如果想继续深入可以阅读本教程的英文原版与配套代码 tutorial 目录源码在本仓库运行对应回归测试验证各参数生成的 OpenAPI 模式测试目录为 tests/test_tutorial/test_path_operation_configurations/结合 fastapi/routing.py 中APIRoute与add_api_route的签名理解参数流向在搭建大型 API 项目时还可以参考本仓库中关于 Python 类型注解、请求体与响应模型等进阶教程把元数据配置与类型驱动的校验能力组合起来。【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考