FastAPI OpenAPI Webhooks 文档化指南用 app.webhooks 声明式描述你的应用将主动推送的事件【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi本篇指南聚焦 FastAPI 的OpenAPI Webhooks特性在 API 的用户需要反向接收你的应用推送通知的场景下如何用app.webhooks在 OpenAPI Schema 与自动生成的文档界面中声明这些事件事件名、HTTP 方法、请求体。读完后你可以完整掌握 Webhooks 的工作流程、可复制的示例代码以及 Webhooks 在 OpenAPI 输出与文档界面中的呈现方式并能深入理解其源码级实现原理。Webhooks 是什么请求方向的反转在常规的 API 交互中是你的用户客户端向你的 API发送请求。但在某些场景下流程恰好相反你的应用或你的 API需要向用户的系统用户的 API、用户的应用发送请求通常是为了通知某个特定**事件Event**的发生。这种模式通常被称为Webhook网络钩子。典型例子支付平台在订单支付完成后向商家回调 URL 推送支付成功通知SaaS 服务在用户新订阅、退订、升级套餐时向客户注册的 URL 推送事件数据。核心特征是目标 URL 不是你的 API 路由而是你的用户在别处例如他们自己的 Dashboard配置并登记的地址由你的代码在适当时机主动向该地址发起请求。Webhooks 的工作流程三方各自负责什么一个完整的 Webhook 机制通常由三方协作完成理解各自职责有助于正确设计 API你在代码中定义消息体Request body明确你希望发送的消息结构即请求体长什么样。这是你 API 契约的一部分也是需要在 OpenAPI 中文档化的核心内容。你定义发送时机触发事件在你的应用中以某种方式定义在哪些时刻这些请求/事件会被发出例如新用户完成订阅后。你的用户定义接收 URL你的用户通过某种方式通常是在一个 Web Dashboard 中登记他们的接收端点 URL你的应用将把请求发送到该 URL。需要注意的一点是Webhook 的 URL 注册逻辑与实际发送请求的代码全部由你自己实现。FastAPI以及 OpenAPI 规范提供的是文档与契约描述能力即告诉你的用户我会发送什么、什么时候发送而具体如何存储用户注册的 URL、何时触发 HTTP 调用是你在自己业务代码中自由编写的。用 FastAPI 与 OpenAPI 文档化 Webhooks借助 FastAPI 对 OpenAPI 的支持你可以在 API 文档中声明这些 Webhooks 的名称事件标识如new-subscription你的应用可能发送的HTTP 操作类型如POST、PUT等你的应用将会发送的Request body结构完整的 JSON Schema。这样做能让你的用户更简单地实现他们那侧的接收端点——他们可以直接阅读你的 OpenAPI 文档甚至自动生成的接口契约在自己的系统中生成接收代码而不需要靠口头约定或截图。版本要求Webhooks 是OpenAPI 3.1.0 及以上规范中的特性从FastAPI0.99.0开始支持。由于当前仓库中 get_openapi 的默认openapi_version参数就是3.1.0因此默认生成的 Schema 版本即可承载 Webhooks 字段。完整示例一个带 Webhooks 的应用下面是一个完整可运行的示例源码位于 docs_src/openapi_webhooks/tutorial001_py310.pyfrom datetime import datetime from fastapi import FastAPI from pydantic import BaseModel app FastAPI() class Subscription(BaseModel): username: str monthly_fee: float start_date: datetime app.webhooks.post(new-subscription) def new_subscription(body: Subscription): When a new user subscribes to your service well send you a POST request with this data to the URL that you register for the event new-subscription in the dashboard. app.get(/users/) def read_users(): return [Rick, Morty]示例要点逐一拆解Subscription模型定义了 Webhook 请求体的结构username、monthly_fee、start_date三个必填字段。这个 Pydantic 模型会被 FastAPI 转成 OpenAPI 的组件 Schema#/components/schemas/Subscription你的用户据此就能知道每个字段的数据类型与是否必填。app.webhooks.post(new-subscription)这就是定义 Webhook 的装饰器用法与你写普通路径操作app.post()等几乎一致只是挂在app.webhooks这个特殊属性上。文档字符串函数的 docstring 会作为 Webhook 的description出现在 OpenAPI Schema 中向用户解释触发时机 发送内容 URL 在哪登记这是面向用户的关键说明。/users/常规路径操作与 Webhook 定义共存用于演示文档中两类条目的并列呈现。app.webhooks就是一个APIRouterapp.webhooks对象实际上就是一个APIRouter——与你把大型应用拆分成多文件、多路由模块时使用的类型完全相同。这一点可以从 FastAPI 应用类源码 得到印证self.webhooks: Annotated[ routing.APIRouter, Doc( The app.webhooks attribute is an APIRouter with the *path operations* that will be used just for documentation of webhooks. ... ), ] webhooks or routing.APIRouter()这意味着你可以在app.webhooks上使用APIRouter的全部能力同样的装饰器风格、同样的 Pydantic 请求体解析、同样的依赖注入dependencies与安全方案声明只是这些路由仅用于文档不会被注册到实际应用的路由树中。Webhook 的路径其实只是一个标签定义 Webhook 时注意你并没有声明一个真实的路径如/items/。装饰器中传入的字符串如new-subscription只是这个 Webhook 的标识事件名在app.webhooks.post(new-subscription)中new-subscription就是 Webhook 名称。之所以这样设计是因为真正的 URL 路径预期由你的用户以其他方式定义例如在他们的 Dashboard 中为每个事件登记接收地址。你的应用只需承诺当new-subscription事件发生时我会 POST 这样一个请求体而POST 到哪个 URL由用户侧数据驱动。测试文档效果在示例目录中启动应用并访问http://127.0.0.1:8000/docsuvicorn tutorial001_py310:app --reload打开文档界面后你会看到与普通路径操作并列的Webhooks分组如上文配图所示常规部分显示GET /users/路径操作Webhooks 部分显示POST new-subscription展开后包含描述文本、无参数的说明、Request bodyrequired的示例值与 Schema 标签页以及 Responses200、422信息。你的用户可以直接在这个界面中查看事件契约甚至基于/openapi.json做自动化处理。源码级实现Webhooks 如何进入 OpenAPI Schema1. 路由上下文统一处理在 get_openapi 函数中普通路由与 Webhooks 被一起纳入字段收集与模型定义生成webhook_paths: dict[str, dict[str, Any]] {} ... all_fields get_fields_from_routes(list(routes) list(webhooks or [])) ... for webhook_context in routing.iter_route_contexts(webhooks or []): api_webhook _get_api_route_for_openapi(webhook_context) if api_webhook is not None: result get_openapi_path(...) if result: path, security_schemes, path_definitions result if path: webhook_paths.setdefault(api_webhook.path_format, {}).update(path) ... if webhook_paths: output[webhooks] webhook_paths可以看到Webhook 路由与常规路由走同一套get_openapi_path处理逻辑参数解析、请求体 Schema、响应声明只是最终结果被写入独立的webhook_paths字典并作为顶层webhooks字段输出——这正是 OpenAPI 3.1.0 对 Webhooks 的规定位置。只有当至少定义了一个 Webhook 时webhooks键才会出现在输出中。2. Schema 模型中的webhooks字段在 OpenAPI 文档模型 fastapi/openapi/models.py 中webhooks被声明为webhooks: dict[str, PathItem | Reference] | None None即一个从**事件名到PathItem或引用**的字典。这与 OpenAPI 规范中webhooks对象的结构一致键是 Webhook 名称值描述该事件下各 HTTP 方法的操作定义。3. 从测试快照看真实输出结构测试 tests/test_webhooks_security.py 断言了完整的/openapi.json输出可以据此确认 Webhooks 在 Schema 中的真实形态{ openapi: 3.1.0, info: {title: FastAPI, version: 0.1.0}, paths: {}, webhooks: { new-subscription: { post: { summary: New Subscription, description: When a new user subscribes to your service ..., operationId: new_subscriptionnew_subscription_post, requestBody: { content: { application/json: { schema: {$ref: #/components/schemas/Subscription} } }, required: true }, responses: { 200: {description: Successful Response, ...: ...}, 422: {description: Validation Error, ...: ...} }, security: [{HTTPBearer: []}] } } }, components: { schemas: {Subscription: {...: ...}}, securitySchemes: {HTTPBearer: {type: http, scheme: bearer}} } }这份快照还揭示了一个实用细节Webhook 操作可以声明安全方案。测试中的应用示例为 Webhook 加上了HTTPBearer安全依赖bearer_scheme HTTPBearer() app.webhooks.post(new-subscription) def new_subscription( body: Subscription, token: Annotated[str, Security(bearer_scheme)] ): ...由于 Webhook 请求体中包含敏感数据用户名、费用等你完全可以在文档中向用户声明发送该请求时会携带 Bearer Token并让components.securitySchemes一并输出对应的方案定义如{HTTPBearer: {type: http, scheme: bearer}}让你的用户知道需要校验什么凭证。这在支付、订阅等涉及敏感数据的回调场景中尤其有价值。小结文档是 Webhook 契约的一半回顾本文的核心要点Webhooks 是请求方向的反转你的应用向用户的系统发送请求以通知事件接收 URL 由用户侧登记发送逻辑由你的业务代码自行实现。FastAPI 提供契约文档能力通过app.webhooks.post(事件名)这类装饰器把事件名、HTTP 方法、请求体 Schema、描述甚至安全方案声明进 OpenAPI Schema 与文档界面让用户可以据此实现甚至自动生成接收端点。适用前提需要 OpenAPI 3.1.0 及以上规范、FastAPI0.99.0及以上版本app.webhooks本质是APIRouter其路由仅用于文档不进入应用真实路由树Webhook 的路径参数只是事件标识而非真实 URL 路径。相关仓库路径供深入阅读示例源码 docs_src/openapi_webhooks/tutorial001_py310.py、Webhook 属性定义 fastapi/applications.py、OpenAPI 生成逻辑 fastapi/openapi/utils.py、Schema 模型 fastapi/openapi/models.py、含安全方案的测试 tests/test_webhooks_security.py。【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 FastAPI OpenAPI Webhooks 文档化指南：用 app.webhooks 声明式描述你的应用将主动推送的事件
FastAPI OpenAPI Webhooks 文档化指南用 app.webhooks 声明式描述你的应用将主动推送的事件【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi本篇指南聚焦 FastAPI 的OpenAPI Webhooks特性在 API 的用户需要反向接收你的应用推送通知的场景下如何用app.webhooks在 OpenAPI Schema 与自动生成的文档界面中声明这些事件事件名、HTTP 方法、请求体。读完后你可以完整掌握 Webhooks 的工作流程、可复制的示例代码以及 Webhooks 在 OpenAPI 输出与文档界面中的呈现方式并能深入理解其源码级实现原理。Webhooks 是什么请求方向的反转在常规的 API 交互中是你的用户客户端向你的 API发送请求。但在某些场景下流程恰好相反你的应用或你的 API需要向用户的系统用户的 API、用户的应用发送请求通常是为了通知某个特定**事件Event**的发生。这种模式通常被称为Webhook网络钩子。典型例子支付平台在订单支付完成后向商家回调 URL 推送支付成功通知SaaS 服务在用户新订阅、退订、升级套餐时向客户注册的 URL 推送事件数据。核心特征是目标 URL 不是你的 API 路由而是你的用户在别处例如他们自己的 Dashboard配置并登记的地址由你的代码在适当时机主动向该地址发起请求。Webhooks 的工作流程三方各自负责什么一个完整的 Webhook 机制通常由三方协作完成理解各自职责有助于正确设计 API你在代码中定义消息体Request body明确你希望发送的消息结构即请求体长什么样。这是你 API 契约的一部分也是需要在 OpenAPI 中文档化的核心内容。你定义发送时机触发事件在你的应用中以某种方式定义在哪些时刻这些请求/事件会被发出例如新用户完成订阅后。你的用户定义接收 URL你的用户通过某种方式通常是在一个 Web Dashboard 中登记他们的接收端点 URL你的应用将把请求发送到该 URL。需要注意的一点是Webhook 的 URL 注册逻辑与实际发送请求的代码全部由你自己实现。FastAPI以及 OpenAPI 规范提供的是文档与契约描述能力即告诉你的用户我会发送什么、什么时候发送而具体如何存储用户注册的 URL、何时触发 HTTP 调用是你在自己业务代码中自由编写的。用 FastAPI 与 OpenAPI 文档化 Webhooks借助 FastAPI 对 OpenAPI 的支持你可以在 API 文档中声明这些 Webhooks 的名称事件标识如new-subscription你的应用可能发送的HTTP 操作类型如POST、PUT等你的应用将会发送的Request body结构完整的 JSON Schema。这样做能让你的用户更简单地实现他们那侧的接收端点——他们可以直接阅读你的 OpenAPI 文档甚至自动生成的接口契约在自己的系统中生成接收代码而不需要靠口头约定或截图。版本要求Webhooks 是OpenAPI 3.1.0 及以上规范中的特性从FastAPI0.99.0开始支持。由于当前仓库中 get_openapi 的默认openapi_version参数就是3.1.0因此默认生成的 Schema 版本即可承载 Webhooks 字段。完整示例一个带 Webhooks 的应用下面是一个完整可运行的示例源码位于 docs_src/openapi_webhooks/tutorial001_py310.pyfrom datetime import datetime from fastapi import FastAPI from pydantic import BaseModel app FastAPI() class Subscription(BaseModel): username: str monthly_fee: float start_date: datetime app.webhooks.post(new-subscription) def new_subscription(body: Subscription): When a new user subscribes to your service well send you a POST request with this data to the URL that you register for the event new-subscription in the dashboard. app.get(/users/) def read_users(): return [Rick, Morty]示例要点逐一拆解Subscription模型定义了 Webhook 请求体的结构username、monthly_fee、start_date三个必填字段。这个 Pydantic 模型会被 FastAPI 转成 OpenAPI 的组件 Schema#/components/schemas/Subscription你的用户据此就能知道每个字段的数据类型与是否必填。app.webhooks.post(new-subscription)这就是定义 Webhook 的装饰器用法与你写普通路径操作app.post()等几乎一致只是挂在app.webhooks这个特殊属性上。文档字符串函数的 docstring 会作为 Webhook 的description出现在 OpenAPI Schema 中向用户解释触发时机 发送内容 URL 在哪登记这是面向用户的关键说明。/users/常规路径操作与 Webhook 定义共存用于演示文档中两类条目的并列呈现。app.webhooks就是一个APIRouterapp.webhooks对象实际上就是一个APIRouter——与你把大型应用拆分成多文件、多路由模块时使用的类型完全相同。这一点可以从 FastAPI 应用类源码 得到印证self.webhooks: Annotated[ routing.APIRouter, Doc( The app.webhooks attribute is an APIRouter with the *path operations* that will be used just for documentation of webhooks. ... ), ] webhooks or routing.APIRouter()这意味着你可以在app.webhooks上使用APIRouter的全部能力同样的装饰器风格、同样的 Pydantic 请求体解析、同样的依赖注入dependencies与安全方案声明只是这些路由仅用于文档不会被注册到实际应用的路由树中。Webhook 的路径其实只是一个标签定义 Webhook 时注意你并没有声明一个真实的路径如/items/。装饰器中传入的字符串如new-subscription只是这个 Webhook 的标识事件名在app.webhooks.post(new-subscription)中new-subscription就是 Webhook 名称。之所以这样设计是因为真正的 URL 路径预期由你的用户以其他方式定义例如在他们的 Dashboard 中为每个事件登记接收地址。你的应用只需承诺当new-subscription事件发生时我会 POST 这样一个请求体而POST 到哪个 URL由用户侧数据驱动。测试文档效果在示例目录中启动应用并访问http://127.0.0.1:8000/docsuvicorn tutorial001_py310:app --reload打开文档界面后你会看到与普通路径操作并列的Webhooks分组如上文配图所示常规部分显示GET /users/路径操作Webhooks 部分显示POST new-subscription展开后包含描述文本、无参数的说明、Request bodyrequired的示例值与 Schema 标签页以及 Responses200、422信息。你的用户可以直接在这个界面中查看事件契约甚至基于/openapi.json做自动化处理。源码级实现Webhooks 如何进入 OpenAPI Schema1. 路由上下文统一处理在 get_openapi 函数中普通路由与 Webhooks 被一起纳入字段收集与模型定义生成webhook_paths: dict[str, dict[str, Any]] {} ... all_fields get_fields_from_routes(list(routes) list(webhooks or [])) ... for webhook_context in routing.iter_route_contexts(webhooks or []): api_webhook _get_api_route_for_openapi(webhook_context) if api_webhook is not None: result get_openapi_path(...) if result: path, security_schemes, path_definitions result if path: webhook_paths.setdefault(api_webhook.path_format, {}).update(path) ... if webhook_paths: output[webhooks] webhook_paths可以看到Webhook 路由与常规路由走同一套get_openapi_path处理逻辑参数解析、请求体 Schema、响应声明只是最终结果被写入独立的webhook_paths字典并作为顶层webhooks字段输出——这正是 OpenAPI 3.1.0 对 Webhooks 的规定位置。只有当至少定义了一个 Webhook 时webhooks键才会出现在输出中。2. Schema 模型中的webhooks字段在 OpenAPI 文档模型 fastapi/openapi/models.py 中webhooks被声明为webhooks: dict[str, PathItem | Reference] | None None即一个从**事件名到PathItem或引用**的字典。这与 OpenAPI 规范中webhooks对象的结构一致键是 Webhook 名称值描述该事件下各 HTTP 方法的操作定义。3. 从测试快照看真实输出结构测试 tests/test_webhooks_security.py 断言了完整的/openapi.json输出可以据此确认 Webhooks 在 Schema 中的真实形态{ openapi: 3.1.0, info: {title: FastAPI, version: 0.1.0}, paths: {}, webhooks: { new-subscription: { post: { summary: New Subscription, description: When a new user subscribes to your service ..., operationId: new_subscriptionnew_subscription_post, requestBody: { content: { application/json: { schema: {$ref: #/components/schemas/Subscription} } }, required: true }, responses: { 200: {description: Successful Response, ...: ...}, 422: {description: Validation Error, ...: ...} }, security: [{HTTPBearer: []}] } } }, components: { schemas: {Subscription: {...: ...}}, securitySchemes: {HTTPBearer: {type: http, scheme: bearer}} } }这份快照还揭示了一个实用细节Webhook 操作可以声明安全方案。测试中的应用示例为 Webhook 加上了HTTPBearer安全依赖bearer_scheme HTTPBearer() app.webhooks.post(new-subscription) def new_subscription( body: Subscription, token: Annotated[str, Security(bearer_scheme)] ): ...由于 Webhook 请求体中包含敏感数据用户名、费用等你完全可以在文档中向用户声明发送该请求时会携带 Bearer Token并让components.securitySchemes一并输出对应的方案定义如{HTTPBearer: {type: http, scheme: bearer}}让你的用户知道需要校验什么凭证。这在支付、订阅等涉及敏感数据的回调场景中尤其有价值。小结文档是 Webhook 契约的一半回顾本文的核心要点Webhooks 是请求方向的反转你的应用向用户的系统发送请求以通知事件接收 URL 由用户侧登记发送逻辑由你的业务代码自行实现。FastAPI 提供契约文档能力通过app.webhooks.post(事件名)这类装饰器把事件名、HTTP 方法、请求体 Schema、描述甚至安全方案声明进 OpenAPI Schema 与文档界面让用户可以据此实现甚至自动生成接收端点。适用前提需要 OpenAPI 3.1.0 及以上规范、FastAPI0.99.0及以上版本app.webhooks本质是APIRouter其路由仅用于文档不进入应用真实路由树Webhook 的路径参数只是事件标识而非真实 URL 路径。相关仓库路径供深入阅读示例源码 docs_src/openapi_webhooks/tutorial001_py310.py、Webhook 属性定义 fastapi/applications.py、OpenAPI 生成逻辑 fastapi/openapi/utils.py、Schema 模型 fastapi/openapi/models.py、含安全方案的测试 tests/test_webhooks_security.py。【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考