OpenAPI Webhooks

在某些情况下，您希望告诉 API 用户您的应用程序可以调用他们的应用程序 (发送请求)，通常是为了通知某种类型的事件。

这意味着，与用户向您的 API 发送请求的正常过程相反，是您的 API (或您的应用程序) 向他们的系统发送请求 (向他们的 API、他们的应用程序)。

这通常称为webhook。

Webhooks 步骤

此过程通常是您在代码中定义要发送的消息，即请求主体。

您还以某种方式定义应用程序何时发送这些请求或事件。

您的用户则以某种方式 (例如，在某个 Web 仪表板中) 定义应用程序应发送这些请求的URL。

关于如何注册 webhooks 的 URL 以及实际发送这些请求的代码的所有逻辑都由您决定。您可以按照自己想要的方式在自己的代码中编写它。

使用 FastAPI 和 OpenAPI 文档化 webhooks

使用 FastAPI 和 OpenAPI，您可以定义这些 webhooks 的名称、应用程序可以发送的 HTTP 操作类型 (例如 POST、PUT 等) 以及应用程序将发送的请求主体。

这可以使您的用户更轻松地实施他们的 API 来接收您的webhook 请求，他们甚至可以自动生成一些自己的 API 代码。

信息

Webhooks 在 OpenAPI 3.1.0 及更高版本中可用，受 FastAPI 0.99.0 及更高版本支持。

具有 webhooks 的应用程序

创建 FastAPI 应用程序时，有一个 webhooks 属性可用于定义webhooks，就像定义路径操作一样，例如使用 @app.webhooks.post()。

from 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 we'll 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"]

您定义的 webhooks 最终会出现在 OpenAPI 架构和自动文档 UI 中。

信息

app.webhooks 对象实际上只是一个 APIRouter，与您在使用多个文件构建应用程序时使用的类型相同。

请注意，使用 webhooks，您实际上并没有声明路径 (例如 /items/)，您传递的文本只是一个 webhook 的标识符 (事件的名称)，例如在 @app.webhooks.post("new-subscription") 中，webhook 名称是 new-subscription。

这是因为预计您的用户会以其他方式 (例如，Web 仪表板) 定义他们希望接收 webhook 请求的实际URL 路径。

检查文档

现在您可以启动您的应用程序并访问 http://127.0.0.1:8000/docs。

您将看到您的文档中包含正常的路径操作，现在还包含一些webhooks