FastAPI path operation 高级配置operationId、include_in_schema、docstring 截断与 openapi_extra 全解析【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi本篇基于 FastAPI 官方文档《Path Operation の高度な設定》日文版展开系统讲解path operation级别的 OpenAPI 高级配置如何自定义operation_id、如何用include_in_schema将路由从自动文档中隐藏、如何用\f字符控制 docstring 进入 OpenAPI 的描述长度以及如何通过openapi_extra扩展甚至重写 OpenAPI 的 Operation Object。读完本文你将掌握在不改动 FastAPI 自动文档机制的前提下对每个路由的 OpenAPI 元数据做精确控制的完整手段并能结合仓库源码理解每个参数的底层实现位置。一、自定义 OpenAPIoperationId1. 通过operation_id参数指定每个path operation即路由函数在生成的 OpenAPI 文档中都会有一个operationId。如果默认的命名规则不符合你的需要例如你在为 API 生成客户端代码时希望使用稳定的、自定义的标识符可以直接在路由装饰器中传入operation_id参数from fastapi import FastAPI app FastAPI() app.get(/items/, operation_idsome_specific_id_you_define) async def read_items(): return [{item_id: Foo}]完整示例见 tutorial001_py310.py。注意事项官方文档明确警告除非你是 OpenAPI 的专家否则通常不需要手动指定operationId手动指定的operation_id必须在整个 API 中唯一多个路由不能重复使用同一个值。2. 使用函数名作为 operationIdgenerate_unique_id_function如果你希望统一地用path operation 函数名作为operationId而不是默认的函数名路径方法组合可以给FastAPI传入一个自定义的generate_unique_id_functionfrom fastapi import FastAPI from fastapi.routing import APIRoute def custom_generate_unique_id(route: APIRoute) - str: return route.name app FastAPI(generate_unique_id_functioncustom_generate_unique_id) app.get(/items/) async def read_items(): return [{item_id: Foo}]完整示例见 tutorial002_py310.py。这个自定义函数的签名是接收每个APIRoute并返回字符串形式的operationId。官方文档警告采用这种方式时每个path operation 函数必须具有唯一的名字即使它们分布在不同模块不同 Python 文件中——因为函数名route.name本身并不包含模块路径不同文件里同名的函数会产生冲突。默认算法的源码佐证仓库中 FastAPI 内置的generate_unique_id位于 fastapi/utils.py其实现为def generate_unique_id(route: APIRoute) - str: operation_id f{route.name}{route.path_format} operation_id re.sub(r\W, _, operation_id) assert route.methods operation_id f{operation_id}_{list(route.methods)[0].lower()} return operation_id即函数名 路径格式拼接后把所有非单词字符替换为下划线再追加小写化的首个 HTTP 方法。这也解释了为什么文档示例中/items/的 GET 路由生成了read_items_items__get这样的 operationIdread_items/items/转下划线 _get。该函数在 fastapi/openapi/utils.py 中被导入用于构建 Operation Object而路由层对它的覆盖逻辑DefaultPlaceholder继承自 Router 的机制集中在 fastapi/routing.py 中——从源码结构看generate_unique_id_function支持在FastAPI、APIRouter以及include_router三个层级配置并逐层继承。二、从 OpenAPI 中排除路由include_in_schemaFalse有时某个path operation仍然需要正常工作但不希望出现在生成的 OpenAPI Schema也就是自动文档中。只需将include_in_schema参数设为Falsefrom fastapi import FastAPI app FastAPI() app.get(/items/, include_in_schemaFalse) async def read_items(): return [{item_id: Foo}]完整示例见 tutorial003_py310.py。设置后该路由的接口依然可以正常访问但不会出现在 Swagger UI / ReDoc 文档以及/openapi.json中。这对内部接口、健康检查端点或尚在调试中的路由非常实用。三、docstring 描述的精确控制\f截断path operation 函数的 docstring 会被 FastAPI 用作 OpenAPI 中该操作的描述文本。当 docstring 较长时可以用转义的换页符form feed\f来划定边界——FastAPI 只取\f之前的部分作为 OpenAPI 描述\f之后的内容不进入文档但仍可被 Sphinx 等其他文档工具使用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 \f :param item: User input. return item完整示例见 tutorial004_py310.py。注意\f位于列表之后、:param item:之前列表部分会进入 OpenAPI 描述而 Sphinx 风格的参数说明则被截断在文档之外。源码级实现截断逻辑就在路由注册阶段完成。fastapi/routing.py 中有如下代码# if a form feed character (page break) is found in the description text, # truncate description text to the content preceding the first form feed route.description route.description.split(\f)[0].strip()即找到第一个换页符取之前的内容并strip()。类似的截断还出现在 Pydantic v2 兼容层中fastapi/_compat/v2.py 对字段描述也做了同样的split(\f)[0]处理说明这一约定贯穿了 OpenAPI 描述生成的多个环节。四、附加响应additional responses你已经见过在path operation上声明response_model与status_code的方式它定义了该操作主响应的元数据。除此之外还可以声明更多附加响应各自的模型、状态码等。官方文档将其单独成章详见 OpenAPI 的附加响应日文版对应的仓库示例代码位于 docs_src/additional_responses/ 目录。五、openapi_extra扩展路径操作的 OpenAPI Schema5.1 Operation Object 与低级别扩展点当你在应用中声明path operation时FastAPI会自动生成与其关联的元数据并放入 OpenAPI Schema这就是 OpenAPI 规范中的Operation Object包含了该操作的全部信息tags、parameters、requestBody、responses等也是自动文档生成的直接依据。openapi_extra参数允许你向这个自动生成的 Schema 中注入额外数据。官方文档将其定位为低级别的扩展点如果只是要添加额外响应更推荐上文提到的附加响应机制只有需要直接操作 Operation Object 时才使用openapi_extra。5.2 声明 OpenAPI Extensionsopenapi_extra最直接用途是声明以x-开头的 OpenAPI 规范扩展Specification Extensionsfrom fastapi import FastAPI app FastAPI() app.get(/items/, openapi_extra{x-aperture-labs-portal: blue}) async def read_items(): return [{item_id: portal-gun}]完整示例见 tutorial005_py310.py。打开自动 API 文档后这个扩展会显示在该path operation的下方而在/openapi.json中它会作为该操作对象的一部分出现{ openapi: 3.1.0, info: { title: FastAPI, version: 0.1.0 }, paths: { /items/: { get: { summary: Read Items, operationId: read_items_items__get, responses: { 200: { description: Successful Response, content: { application/json: { schema: {} } } } }, x-aperture-labs-portal: blue } } } }5.3 自定义 OpenAPIpath operationSchema不依赖 Pydantic 也定义 requestBodyopenapi_extra内的字典会与自动生成的 OpenAPI Schema 进行深度合并deep merge因此你可以向 Schema 中追加原本 FastAPI 不会生成的字段。典型场景你选择不用 Pydantic 的自动功能而是自己读取并校验请求但仍希望在 OpenAPI 中声明请求体的结构。此时可以让端点直接接收Request把原始请求体作为bytes读取同时用openapi_extra手动写requestBodyfrom fastapi import FastAPI, Request app FastAPI() def magic_data_reader(raw_body: bytes): return { size: len(raw_body), content: { name: Maaaagic, price: 42, description: Just kiddin, no magic here. ✨, }, } app.post( /items/, openapi_extra{ requestBody: { content: { application/json: { schema: { required: [name, price], type: object, properties: { name: {type: string}, price: {type: number}, description: {type: string}, }, } } }, required: True, }, }, ) async def create_item(request: Request): raw_body await request.body() data magic_data_reader(raw_body) return data完整示例见 tutorial006_py310.py。这个例子没有声明任何 Pydantic 模型请求体也不会被解析为 JSON而是直接以bytes读取交给magic_data_reader()自行处理但 OpenAPI 文档中依然展示了一个完整、正确的 JSON Schema 请求体定义。5.4 自定义 OpenAPI content typeYAML 请求体同样的技巧还能处理非 JSON 请求内容类型。下面的示例声明请求体的 content type 为application/x-yamlSchema 来自 Pydantic 模型Item手动生成的 JSON Schema但完全不使用 FastAPI 的 JSON 自动解析/校验功能import yaml from fastapi import FastAPI, HTTPException, Request from pydantic import BaseModel, ValidationError app FastAPI() class Item(BaseModel): name: str tags: list[str] app.post( /items/, openapi_extra{ requestBody: { content: {application/x-yaml: {schema: Item.model_json_schema()}}, required: True, }, }, ) async def create_item(request: Request): raw_body await request.body() try: data yaml.safe_load(raw_body) except yaml.YAMLError: raise HTTPException(status_code422, detailInvalid YAML) try: item Item.model_validate(data) except ValidationError as e: raise HTTPException(status_code422, detaile.errors(include_urlFalse)) return item完整示例见 tutorial007_py310.py。该示例的工作流程值得注意Schema 生成Item.model_json_schema()从 Pydantic 模型静态抽取 JSON Schema注入openapi_extra的application/x-yamlcontent 段——文档层面正确描述了你期望的 YAML 数据形状原始读取await request.body()拿到bytesFastAPI 甚至不会尝试把它当 JSON 解析手动解析与校验yaml.safe_load解析 YAML解析失败抛出 422再用同一个Item模型model_validate做数据校验校验失败同样返回 422且通过include_urlFalse精简错误输出。官方文档提示这里复用了同一个 Pydantic 模型但你同样可以用其他方式做解析与校验——openapi_extra只关心文档里声明什么与运行时代码怎么处理完全解耦。5.5 合并机制的源码佐证openapi_extra参数在 fastapi/routing.py 中从APIRoute定义开始贯穿APIRouter、include_router以及所有get/post/put/patch/delete...装饰器透传该文件中有十余处同名参数签名最终在 OpenAPI 构建阶段与自动生成的 Operation Object 深度合并。合并所用的deep_dict_update工具函数定义在 fastapi/utils.py 中并被 fastapi/openapi/utils.py 导入用于 OpenAPI 文档生成流程——从源码结构看openapi_extra的每个键都会递归覆盖/追加到对应路径的操作 Schema 中这保证了你在扩展requestBody时可以只写差异部分而不必重写整个 Operation Object。小结参数作用层级适用场景operation_id单个路由为指定操作设置唯一的自定义 OpenAPIoperationIdgenerate_unique_id_function应用 / 路由器统一改变所有路由的operationId生成规则如直接用函数名include_in_schema单个路由保留接口功能但将其从自动文档中隐藏docstring 中的\f单个路由的 docstring限制进入 OpenAPI 的描述长度其余留给 Sphinx 等工具openapi_extra单个路由低级别扩展 Operation Objectx-扩展字段、自定义requestBody与非 JSON content type以上配置均只影响 OpenAPI 元数据的生成不改变路由本身的实际行为include_in_schema影响文档、openapi_extra只影响 Schema 声明是 FastAPI 提供的一组文档侧精细控制旋钮。所有示例代码均可在 docs_src/path_operation_advanced_configuration/ 目录下运行验证对应的英文对照文档位于 docs/en/docs/advanced/path-operation-advanced-configuration.md。【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考