预览与发布Generation

生成 Webhook 参考文档

以 Markdown 格式查看

Fern 从 OpenAPI 规范 或 Fern Definition 生成 Webhook 参考文档。

Fern 通过以下方式支持 webhooks：

  • OpenAPI 3.1+：使用原生 webhooks 字段配合 operationId（推荐）
  • OpenAPI 3.0：使用 x-fern-webhook: true 扩展
  • Fern Definition：在规范中定义 webhooks

配置

1

设置项目结构

对于 OpenAPI：将规范文件添加到 /fern 目录并创建引用它的 generators.yml：

generators.yml
1api:
2  path: openapi/openapi.yml

对于 Fern Definition：添加包含 webhook 定义文件的 definition/ 目录（Fern 会自动检测）。

2

将 Webhook 参考文档添加到导航中

在 docs.yml 的导航中添加 - api: Webhook Reference：

docs.yml
1navigation:
2  - api: Webhook Reference
3    api-name: webhooks-v1

使用 api-name 属性引用包含 webhook 定义的文件夹。

3

自定义布局

有关配置选项和布局自定义的完整列表，请参阅自定义 API 参考布局。

有关从 API 定义生成的 webhook 文档的实际示例，请查看 Webflow 的 webhooks。

包含多个 Webhook 参考文档

要在文档中包含多个 webhook 定义，请使用 api-name 属性。api-name 对应包含 webhook 定义的文件夹名称。

fern
fern.config.json
docs.yml
payment-webhooks
openapi
openapi.yml# 支付 webhook OpenAPI 规范
generators.yml
order-webhooks
openapi
openapi.yml# 订单 webhook OpenAPI 规范
generators.yml
docs.yml
1navigation:
2  - api: Payment Webhooks
3    api-name: payment-webhooks
4  - api: Order Webhooks
5    api-name: order-webhooks

引用单个 webhook 事件

要将每个 webhook 事件显示为单独页面，请在 layout 中使用 subpackage_{tag}.{webhook-event-name} 格式引用：

docs.yml
1navigation:
2  - api: Webhook Reference
3    api-name: webhooks-v1
4    layout:
5      - subpackage_plants.newPlantWebhook

其中 {tag} 是第一个标签（小写），{webhook-event-name} 是 webhook 定义中的 operationId。

对于 OpenAPI，您必须在 webhook 规范 中定义 tags 和 example 属性。