2.9 KiB
OpenAPI 网络钩子
有些情况下，您可能想告诉您的 API 用户，您的应用程序可以携带一些数据调用他们的应用程序（给它们发送请求），通常是为了通知某种事件。
这意味着，除了您的用户向您的 API 发送请求的一般情况，您的 API（或您的应用）也可以向他们的系统（他们的 API、他们的应用）发送请求。
这通常被称为网络钩子（Webhook）。
使用网络钩子的步骤
通常的过程是您在代码中定义要发送的消息，即请求的主体。
您还需要以某种方式定义您的应用程序将在何时发送这些请求或事件。
用户会以某种方式（例如在某个网页仪表板上）定义您的应用程序发送这些请求应该使用的 URL。
所有关于注册网络钩子的 URL 的逻辑以及发送这些请求的实际代码都由您决定。您可以在自己的代码中以任何想要的方式来编写它。
使用 FastAPI 和 OpenAPI 文档化网络钩子
使用 FastAPI，您可以利用 OpenAPI 来自定义这些网络钩子的名称、您的应用可以发送的 HTTP 操作类型（例如 POST、PUT 等）以及您的应用将发送的请求体。
这能让您的用户更轻松地实现他们的 API 来接收您的网络钩子请求，他们甚至可能能够自动生成一些自己的 API 代码。
/// info
网络钩子在 OpenAPI 3.1.0 及以上版本中可用，FastAPI 0.99.0 及以上版本支持。
///
带有网络钩子的应用程序
当您创建一个 FastAPI 应用程序时，有一个 webhooks 属性可以用来定义网络钩子，方式与您定义路径操作的时候相同，例如使用 @app.webhooks.post() 。
{* ../../docs_src/openapi_webhooks/tutorial001.py hl[9:13,36:53] *}
您定义的网络钩子将被包含在 OpenAPI 的架构中，并出现在自动生成的文档 UI 中。
/// info
app.webhooks 对象实际上只是一个 APIRouter ，与您在使用多个文件来构建应用程序时所使用的类型相同。
///
请注意，使用网络钩子时，您实际上并没有声明一个路径（比如 /items/ ），您传递的文本只是这个网络钩子的标识符（事件的名称）。例如在 @app.webhooks.post("new-subscription") 中，网络钩子的名称是 new-subscription 。
这是因为我们预计您的用户会以其他方式（例如通过网页仪表板）来定义他们希望接收网络钩子的请求的实际 URL 路径。
查看文档
现在您可以启动您的应用程序并访问 http://127.0.0.1:8000/docs.
您会看到您的文档不仅有正常的路径操作显示，现在还多了一些网络钩子：
