首页
/ FastAPI Path Operation 高级配置实战：operationId、include_in_schema 与 openapi_extra 完全指南

FastAPI Path Operation 高级配置实战：operationId、include_in_schema 与 openapi_extra 完全指南

2026-09-07 15:45:19作者：江焘钦
fastapi
FastAPI framework, high performance, easy to learn, fast to code, ready for production
项目地址：https://gitcode.com/GitHub_Trending/fa/fastapi

Path Operation 是 FastAPI 中最基本的单元——每个路由装饰器（如 @app.get()）背后都会生成一份对应的 OpenAPI Operation Object 元数据，并被自动文档与 /openapi.json 使用。本文基于本仓库文档 path-operation-advanced-configuration.md 及其完整示例源码，系统讲解如何深度定制单个 Path Operation 的 OpenAPI 元数据，涵盖：自定义 operationId、用函数名一键生成 operationId、将接口从 OpenAPI 中排除、利用 \f 控制 docstring 截断，以及通过 openapi_extra 注入扩展字段、自定义请求体 Schema 甚至非 JSON 的 content type。读完你将具备手工雕刻"文档可见层"之外全部 OpenAPI 细节的能力。

提示：以下所有可运行代码均取自仓库 docs_src/path_operation_advanced_configuration/，源码使用 Python 3.10+ 语法。

OpenAPI operationId：为每个接口指定唯一标识

operationId 是 OpenAPI 中每个操作（HTTP 方法与路径组合）的机器可读唯一标识，客户端生成器（如 OpenAPI Generator、各语言的 API SDK 生成工具）通常直接以它为函数或方法命名。

在 FastAPI 中，你可以直接通过 path operation 装饰器的 operation_id 参数来显式指定：

from fastapi import FastAPI

app = FastAPI()


@app.get("/items/", operation_id="some_specific_id_you_define")
async def read_items():
    return [{"item_id": "Foo"}]

对应示例文件：tutorial001_py310.py。

从仓库源码结构看，operation_id 作为装饰器参数传入后会记录在路由的 APIRoute 对象上（参见 fastapi/routing.py 中路由的构建逻辑），最终在生成 OpenAPI schema 时被写入该路径项的 operationId 字段。需要特别注意的是，你必须确保它为每个操作保持唯一，否则生成的 OpenAPI 文档会包含重复标识，影响下游代码生成工具的可靠性。

使用 path operation function 名称作为 operationId

如果你希望 API 的函数名直接作为 operationId（例如让你的 Python 函数名与生成的客户端方法名一一对应），不必在每个装饰器里手写 operation_id，而是可以给 FastAPI 实例传入一个自定义的 generate_unique_id_function。

该函数接收每个 APIRoute，并返回该 path operation 要使用的 operationId：

from fastapi import FastAPI
from fastapi.routing import APIRoute


def custom_generate_unique_id(route: APIRoute) -> str:
    return route.name


app = FastAPI(generate_unique_id_function=custom_generate_unique_id)


@app.get("/items/")
async def read_items():
    return [{"item_id": "Foo"}]

对应示例文件：tutorial002_py310.py。

这段代码的关键点在于：

  • route.name 就是 path operation function 的函数名（此处为 read_items）；
  • FastAPI(generate_unique_id_function=...) 是应用级配置，它替换了默认的 operationId 生成策略（默认策略会拼接函数名、路径与方法，例如 read_items_items__get）；
  • 传入的 callable 会被用于为应用中的每一个路由生成唯一 ID，APIRoute 类型来自 fastapi/routing.py。

⚠️ 使用函数名时的唯一性要求

采用此方案后，你必须自行确保所有 path operation functions 的函数名全局唯一——即使它们分布在不同的模块（Python 文件）中也不能重名。一旦两个路由的函数名相同，生成的 operationId 就会冲突，破坏 OpenAPI 的语义。这是一个容易在大型项目中踩中的坑，建议为函数命名时保持模块前缀或业务前缀的一致性。

从 OpenAPI 中排除某个接口（include_in_schema）

并非所有接口都适合暴露在 OpenAPI schema 与自动文档中。典型场景包括：

  • 仅供内部调用的健康检查、调试接口；
  • 尚未就绪、不希望外部看到的路由；
  • 出于文档整洁性考虑而隐藏的低层接口。

使用 include_in_schema 参数并将其设为 False，即可让该 path operation 从生成的 OpenAPI schema（以及依赖它的自动文档系统）中完全移除：

from fastapi import FastAPI

app = FastAPI()


@app.get("/items/", include_in_schema=False)
async def read_items():
    return [{"item_id": "Foo"}]

对应示例文件：tutorial003_py310.py。

注意：该接口仍可被正常访问与调用，只是不出现在 /openapi.json、/docs（Swagger UI）与 /redoc 中。如果你需要的是"拒绝外部访问"而不是"从文档中隐藏"，则应当改用认证/权限机制而非此参数。

利用 docstring 生成进阶描述：\f form feed 截断

默认情况下，FastAPI 会把 path operation function 的 docstring 用作该接口的 OpenAPI description（Markdown 会被渲染）。但当 docstring 需要同时服务于两种不同用途的读者时——一部分内容面向 OpenAPI 文档，其余内容面向 Sphinx 等 API 工具——你可以在 docstring 中插入一个转义的 form feed 字符 \f。

FastAPI 检测到 \f 后，会在该位置截断用于 OpenAPI 的输出；\f 本身不会显示在文档中，而 \f 之后的内容依然保留在 docstring 里，可被其他工具（如 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/", summary="Create 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 doesn't 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 之前的部分（带 Markdown 列表的说明文字）会成为该 POST 接口在自动文档中的 description；
  • \f 之后的 :param item: User input. 等 Sphinx/工具风格的段落不会被 FastAPI 放入 OpenAPI，从而避免两种文档格式互相污染。

附加 Responses（Additional Responses）

你此前可能已经了解如何为某个 path operation 声明 response_model 与 status_code——这两者定义了该操作主响应的元数据。除此之外，你还可以为同一操作声明附加的响应，例如 404、422 或其他业务状态码，并分别给出其响应模型与描述。

本主题内容较多，仓库文档为此专门设有独立章节，完整讲解请阅读 OpenAPI 中的附加 Responses。需要指出的是，声明附加响应通常并不需要 openapi_extra，FastAPI 提供了更便捷的参数（如 responses），因此建议优先使用专门的机制。

OpenAPI Extra：低层扩展点

当你声明一个 path operation 时，FastAPI 会自动生成关于它的元数据并纳入 OpenAPI schema。这一份"操作对象"（OpenAPI 规范中称为 Operation Object）包含了该操作的全部信息——tags、parameters、requestBody、responses 等，正是它驱动着自动文档的生成。

正常情况下这份元数据完全由 FastAPI 自动产生，但框架同时提供了一个低层扩展点：openapi_extra 参数，允许你手工为某个操作的 schema 追加自定义内容。

需要说明的是，openapi_extra 属于相对底层的 API。如果你只是想声明附加响应，请优先阅读上节指向的 附加 Responses 章节，那里的方式要便捷得多。

OpenAPI Extensions：自定义 x- 扩展字段

一个非常典型的 openapi_extra 用法是声明 OpenAPI 规范定义的 Specification Extensions——即以 x- 前缀开头的自定义字段。这类字段会被客户端工具、内部网关或文档站点等消费，用于扩展操作的行为或描述。

例如为接口附加一个厂商门户字段：

from 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 区块的底部，效果如下：

FastAPI 自动文档中显示的 x-aperture-labs-portal 自定义扩展字段

如果你查看最终生成的 OpenAPI（访问应用的 /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"
            }
        }
    }
}

注意 x-aperture-labs-portal 与 summary、operationId、responses 并列，处于 /items/ 下 get 这个 Operation Object 之内。

自定义 OpenAPI path operation schema

openapi_extra 中提供的字典会与 FastAPI 为该 path operation 自动生成的 OpenAPI schema 做深度合并（deep merge）。因此你可以在自动 schema 之上追加任意附加数据，包括覆盖或补充 requestBody 等标准部分。

一个典型的现实诉求是：你希望完全用自己的代码来读取并校验请求，不借助 FastAPI 基于 Pydantic 的自动特性，但同时又希望把请求的 schema 定义进 OpenAPI 供文档与代码生成使用。openapi_extra 可以做到这一点：

from 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 model；
  • 请求体甚至没有被当作 JSON 解析——它通过 await request.body() 被直接读取为 bytes，具体的解析完全交给 magic_data_reader() 这类自定义函数；
  • 尽管如此，借助 openapi_extra 我们依然为请求体声明了符合预期的 JSON Schema（required + properties），让自动文档与代码生成工具能够正确理解该接口的入参结构。

结合本仓库的路由实现来看（参见 fastapi/routing.py），openapi_extra 与 operation_id、include_in_schema 等同属路径操作配置参数，最终作用于 OpenAPI 生成阶段，使开发者能够在框架自动推导之外拥有手工干预的最后手段。

自定义 OpenAPI content type：非 JSON 请求（YAML 示例）

openapi_extra 的合并机制还带来一个进阶用法：用 Pydantic 模型定义 JSON Schema，再把它嵌入到自定义 content type 的 schema 中——即使实际请求的媒体类型根本不是 JSON。

下面的应用刻意不用 FastAPI 从 Pydantic 提取 JSON Schema 的内置功能，也不用 JSON 的自动校验，而是把请求的 content type 声明为 YAML：

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_code=422, detail="Invalid YAML")
    try:
        item = Item.model_validate(data)
    except ValidationError as e:
        raise HTTPException(status_code=422, detail=e.errors(include_url=False))
    return item

对应示例文件：tutorial007_py310.py。

拆解这里的实现策略：

  1. 声明层：虽然不走 FastAPI 默认的 Pydantic 集成路径，但依然通过 Item.model_json_schema() 从 Pydantic 模型手工生成 JSON Schema，并将其填入 application/x-yaml 这个 content type 之下。文档/代码生成工具因此能知道该接口会接收包含 name: string、tags: array[string] 的 YAML 文档。
  2. 请求读取层：函数签名接收 request: Request，raw_body = await request.body() 把 body 提取为 bytes。这意味着 FastAPI 根本不会尝试把请求载荷解析为 JSON。
  3. 解析与校验层：代码中先用 yaml.safe_load(raw_body) 直接解析 YAML 内容；随后再次复用同一个 Pydantic 模型 Item.model_validate(data) 校验解析结果，并把校验错误转为 422 HTTP 响应。

这里复用了同一个 Pydantic 模型，但这并非强制——你完全可以用任何其他方式来校验 YAML 数据，openapi_extra 只负责让文档正确描述请求格式。

源码视角：这些配置参数在哪里生效？

将上述参数串联起来看，它们在仓库中的落点分别是：

  • fastapi/routing.py：定义 APIRoute，承载 operation_id、include_in_schema、openapi_extra 等路径操作配置，并提供 generate_unique_id_function 所需的 route.name 等属性；
  • fastapi/applications.py：FastAPI 应用构造时接收 generate_unique_id_function 等应用级配置，并传递给所有注册路由；
  • docs_src/path_operation_advanced_configuration/：与本文一一对应的七个可直接运行的示例（tutorial001～tutorial007），建议结合源码逐例运行验证。

掌握这一层配置，你就能在"框架自动生成 schema"与"完全手工定义 schema"之间自由取中间态：既要文档准确完整，又不必被自动校验/自动请求体解析限制住——这正是生产级 API 中处理自定义协议、二进制负载与厂商扩展时的常用手段。

fastapi
FastAPI framework, high performance, easy to learn, fast to code, ready for production
项目地址：https://gitcode.com/GitHub_Trending/fa/fastapi
登录后查看全文

相关内容推荐

1 FastAPI 路径操作高级配置：operationId、从 OpenAPI 中隐藏接口与 openapi_extra 深度定制指南2 FastAPI Path Operation 高级配置详解：operationId、include_in_schema、docstring 截断与 openapi_extra 扩展3 FastAPI path operation 高级配置：operationId、include_in_schema、docstring 截断与 openapi_extra 全解析4 FastAPI 路径操作高级配置实战：operationId、include_in_schema 与 openapi_extra 的深度解析5 FastAPI 路径操作高级配置详解：自定义 OpenAPI operationId、从文档排除与 openapi_extra 深度定制6 FastAPI 路径操作高级配置：从 operationId 定制到 openapi_extra 深度扩展实战7 FastAPI 路径操作高级配置指南：operationId 定制、从 OpenAPI 排除与 openapi_extra 扩展8 FastAPI 自定义扩展 OpenAPI schema：用 get_openapi 覆盖默认生成逻辑9 FastAPI 扩展 OpenAPI 架构实战：重写 openapi() 与 get_openapi 自定义 API 文档10 FastAPI APIRouter 类完全参考：多文件模块化路由的构造参数、方法与实现机制
热门项目推荐
相关项目推荐

热门内容推荐

1 编程实践项目探索指南：从零构建技术能力体系2 技术解构式学习：从0到1构建你的编程知识体系3 构建自己的技术世界：build-your-own-x项目的实践探索指南4 解锁编程技能的实践之旅：从零构建你的技术世界5 技术实践探索：从零开始构建核心系统的实践指南6 亲手锻造技术引擎：从0到1构建核心系统的实践指南

最新内容推荐

daisyUI FAB 组件完整实战指南：悬浮按钮、Speed Dial 速拨菜单与 fab-flower 扇形展开three.js TAA 抗锯齿实战：TAARenderPass 时序累积采样后处理全解析OpenHuman Subconscious Factory 重构（Phase 5）落地指南：测试矩阵、文档同步与多实例发布策略curl 的 `--dns-interface` 参数全解析：让 DNS 查询从指定网络接口发出freeCodeCamp 每日编程挑战解析：用 JavaScript 实现 SCREAMING_SNAKE_CASE 变量名转换器Langchain-Chatchat 配置体系实战指南：Settings 统一管理与 YAML 配置模板全解析Langchain-Chatchat 会话模型深度解析：ConversationModel 的表结构、生命周期与多端调用链路Arbor 执行器任务书（Executor Brief）编写指南：用单假设实验契约驱动 scientific-agent-skills 中的 HTR 自主优化three.js 后处理进阶：使用 TexturePass 将纹理/渲染结果铺满整个屏幕ToolJet Marketplace 插件开发实战：使用 tooljet CLI 从零构建 GitHub 数据源插件

项目优选

收起
kernelkernel
deepin linux kernel
C
33
18
ops-transformerops-transformer
本项目是CANN提供的transformer类大模型算子库，实现网络在NPU上加速计算。
C++
1.14 K
2.75 K
pytorchpytorch
作为 Ascend for PyTorch 社区的核心组件，TorchNPU 是昇腾专为 PyTorch 打造的深度学习适配插件，使 PyTorch 框架能够直接调用昇腾 NPU，为开发者提供昇腾 AI 处理器的超强算力。
Python
857
1.35 K
docsdocs
暂无描述
Markdown
898
5.82 K
kernelkernel
openEuler内核是openEuler操作系统的核心，既是系统性能与稳定性的基石，也是连接处理器、设备与服务的桥梁。
C
531
596
ops-nnops-nn
本项目是CANN提供的神经网络类计算算子库，实现网络在NPU上加速计算。
C++
921
1.84 K
jiuwenswarmjiuwenswarm
JiuwenSwarm 是一款基于openJiuwen开发的智能AI Agent，它能够将大语言模型的强大能力，通过你日常使用的各类通讯应用，直接延伸至你的指尖。
Python
3.8 K
1.02 K
ops-mathops-math
本项目是CANN提供的数学类基础计算算子库，实现网络在NPU上加速计算。
C++
1.36 K
1.46 K
cann-learning-hubcann-learning-hub
CANN 学习中心仓，支持在线互动运行、边学边练，提供教程、示例与优化方案，一站式助力昇腾开发者快速上手。
Jupyter Notebook
1.02 K
519
AscendNPU-IRAscendNPU-IR
AscendNPU-IR是基于MLIR（Multi-Level Intermediate Representation）构建的，面向昇腾亲和算子编译时使用的中间表示，提供昇腾完备表达能力，通过编译优化提升昇腾AI处理器计算效率，支持通过生态框架使能昇腾AI处理器与深度调优
C++
548
391