Generation

生成 Webhook 参考文档

以 Markdown 格式查看

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

Fern 通过以下方式支持 webhooks：

  • OpenAPI 3.1+：使用原生的 webhooks 字段和 operationId（推荐）
  • OpenAPI 3.0：使用 x-fern-webhook: true 扩展

配置

1

设置您的项目结构

将您的规范文件添加到 /fern 目录中，并创建一个引用它的 generators.yml：

generators.yml
1api:
2  path: openapi/openapi.yml
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# Payment webhook OpenAPI spec
generators.yml
order-webhooks
openapi
openapi.yml# Order webhook OpenAPI spec
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 事件显示为单独的页面，请使用 subpackage_{tag}.{webhook-event-name} 格式在 layout 中引用它：

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

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

您必须在您的 webhook 规范中定义 tags 和 example 属性。