From cb18f28a1e67b9fd2e273f37aedbf5a4a4db2d5a Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Fri, 29 Aug 2025 15:06:49 -0400 Subject: [PATCH 1/2] initial draft --- .../pages/api-references/generate-webhook-ref.mdx | 13 ++----------- .../snippets/individual-pages-webhook-ferndef.mdx | 15 +++++++++++++++ .../snippets/individual-pages-webhook-openapi.mdx | 10 ++++++++++ 3 files changed, 27 insertions(+), 11 deletions(-) create mode 100644 fern/snippets/individual-pages-webhook-ferndef.mdx create mode 100644 fern/snippets/individual-pages-webhook-openapi.mdx diff --git a/fern/products/docs/pages/api-references/generate-webhook-ref.mdx b/fern/products/docs/pages/api-references/generate-webhook-ref.mdx index 43798975d..8494e08c8 100644 --- a/fern/products/docs/pages/api-references/generate-webhook-ref.mdx +++ b/fern/products/docs/pages/api-references/generate-webhook-ref.mdx @@ -99,15 +99,6 @@ fern/ └── generators.yml ``` -### Create individual documentation pages for each webhook event (OpenAPI) +### Create individual documentation pages for each webhook event -To display each webhook event as an individual page with rich examples, you need to define `tags` and `example` [in your webhook specification](/api-definitions/openapi/endpoints/webhooks) (or [overrides file](/api-definitions/overview/overrides)). - -Then, reference individual webhook pages using the `subpackage_{tag}.{webhook-event-name}` format, where: -- `{tag}` is the first tag (lowercase) from your webhook definition -- `{webhook-event-name}` is the `operationId` from your webhook definition - -```yaml title="docs.yml" -navigation: - - subpackage_plants.newPlantWebhook -``` + diff --git a/fern/snippets/individual-pages-webhook-ferndef.mdx b/fern/snippets/individual-pages-webhook-ferndef.mdx new file mode 100644 index 000000000..4c00c0e32 --- /dev/null +++ b/fern/snippets/individual-pages-webhook-ferndef.mdx @@ -0,0 +1,15 @@ +Reference individual webhook pages using the `subpackage_{api-name}.{webhook-name}`, where `api-name` is the name of the folder: +- `{folder-name}` is the first tag (lowercase) from your webhook definition +- `{webhook-event-name}` is the `operationId` from your webhook definition + +```yaml title="docs.yml" +navigation: + - subpackage_plants.newPlantWebhook +``` + +subpackage_webhooksv2_payInTransactionetc +subpackage_{api_name}.operationID + +operation id defines the webhook + +payload name defines the webhook for fern definition \ No newline at end of file diff --git a/fern/snippets/individual-pages-webhook-openapi.mdx b/fern/snippets/individual-pages-webhook-openapi.mdx new file mode 100644 index 000000000..e3c5a5ffc --- /dev/null +++ b/fern/snippets/individual-pages-webhook-openapi.mdx @@ -0,0 +1,10 @@ +To display each webhook event as an individual page with rich examples, you need to define `tags` and `example` [in your webhook specification](/api-definitions/openapi/endpoints/webhooks) (or [overrides file](/api-definitions/overview/overrides)). + +Then, reference individual webhook pages using the `subpackage_{tag}.{webhook-event-name}` format, where: +- `{tag}` is the first tag (lowercase) from your webhook definition +- `{webhook-event-name}` is the `operationId` from your webhook definition + +```yaml title="docs.yml" +navigation: + - subpackage_plants.newPlantWebhook +``` \ No newline at end of file From a0d6b13aa48e5d0b9ab7f79c230e36c90f84db99 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Wed, 3 Sep 2025 16:24:25 -0400 Subject: [PATCH 2/2] reorganize info, add fern definition syntax --- .../api-def/ferndef-pages/webhooks.mdx | 21 +++++++++ .../api-def/openapi-pages/webhooks.mdx | 35 +++++++++----- .../api-references/generate-webhook-ref.mdx | 46 +++++++++++++++---- .../individual-pages-webhook-ferndef.mdx | 15 ------ .../individual-pages-webhook-openapi.mdx | 10 ---- 5 files changed, 82 insertions(+), 45 deletions(-) delete mode 100644 fern/snippets/individual-pages-webhook-ferndef.mdx delete mode 100644 fern/snippets/individual-pages-webhook-openapi.mdx diff --git a/fern/products/api-def/ferndef-pages/webhooks.mdx b/fern/products/api-def/ferndef-pages/webhooks.mdx index 399c3c2a1..3b164f863 100644 --- a/fern/products/api-def/ferndef-pages/webhooks.mdx +++ b/fern/products/api-def/ferndef-pages/webhooks.mdx @@ -63,3 +63,24 @@ You can inline the schema of the payload by doing the following: ``` +## Generate webhook reference + +Fern Docs can automatically generate your webhook reference documentation from your definition. Set this up in your `docs.yml` file. + +Your webhook reference can be a single documentation page: + +```yml docs.yml +navigation: + - api: Webhook Reference # Display name for this page + api-name: webhooks-v1 # Directory containing webhook definition +``` + +Or you can configure individual documentation pages per webhook event: + +```yaml title="docs.yml" +navigation: + - subpackage_api.newPlantWebhook # Format: subpackage_{name-of-api}.{webhook-event-name} +``` + +For more information on how to configure your webhook reference in `docs.yml`, see [Generate your webhook reference](/docs/api-references/generate-webhook-reference). + diff --git a/fern/products/api-def/openapi-pages/webhooks.mdx b/fern/products/api-def/openapi-pages/webhooks.mdx index 841d1e810..92ff56d62 100644 --- a/fern/products/api-def/openapi-pages/webhooks.mdx +++ b/fern/products/api-def/openapi-pages/webhooks.mdx @@ -8,15 +8,10 @@ Fern supports two methods for defining webhooks in your OpenAPI specification: 1. Using OpenAPI 3.1's native webhook support (recommended) 2. Using Fern's `x-fern-webhook` extension -## OpenAPI 3.1 Webhooks +## OpenAPI 3.1 webhooks For OpenAPI 3.1 specifications, use the `webhooks` top-level field to define your webhook operations. Each webhook requires an `operationId` to be properly processed by Fern. -To create dedicated pages in your API reference documentation for each webhook -event, include `tags` and complete `example` data in your schema. Then, [add a -reference in your -`docs.yml`](/docs/api-references/generate-webhook-reference#create-individual-documentation-pages-for-each-webhook-event-openapi). - ```yaml openapi.yml {4, 7-8, 42-48} webhooks: newPlant: @@ -71,15 +66,10 @@ webhooks: description: Return a 200 status to indicate that the data was received successfully ``` -## Fern Webhook Extension +## Fern webhook extension For OpenAPI 3.0, use the `x-fern-webhook: true` extension to define webhooks. Fern will treat the `requestBody` as the webhook payload. -To create dedicated pages in your API reference documentation for each webhook -event, include `tags` and complete `example` data in your schema. Then, [add a -reference in your -`docs.yml`](/docs/api-references/generate-webhook-reference#create-individual-documentation-pages-for-each-webhook-event-openapi). - ```yaml openapi.yml {6-8, 23-25} paths: /payment/updated/: @@ -112,3 +102,24 @@ paths: The path that you choose when defining a webhook can be arbitrary. Since webhooks can be sent to any server, Fern just ignores the path. + +## Generate webhook reference + +Fern Docs can automatically generate your webhook reference documentation from your definition. Set this up in your `docs.yml` file. + +Your webhook reference can be a single documentation page: + +```yml docs.yml +navigation: + - api: Webhook Reference # Display name for this page + api-name: webhooks-v1 # Name of webhook definition directory +``` + +Or you can configure individual documentation pages per webhook event: + +```yaml title="docs.yml" +navigation: + - subpackage_plants.newPlantWebhook # subpackage_{tag}.{webhook-event-name} +``` + +For more information on how to configure your webhook reference in `docs.yml`, see [Generate your webhook reference](/docs/api-references/generate-webhook-reference). \ No newline at end of file diff --git a/fern/products/docs/pages/api-references/generate-webhook-ref.mdx b/fern/products/docs/pages/api-references/generate-webhook-ref.mdx index 8494e08c8..f2ba56202 100644 --- a/fern/products/docs/pages/api-references/generate-webhook-ref.mdx +++ b/fern/products/docs/pages/api-references/generate-webhook-ref.mdx @@ -1,9 +1,9 @@ --- -title: Generate your Webhook Reference -description: Use Fern Docs to generate your Webhook Reference documentation from your API definition, using your choice of either OpenAPI or Fern Definition. +title: Generate your webhook reference +description: Use Fern Docs to generate your webhook reference documentation from your API definition, using your choice of either OpenAPI or Fern Definition. --- -Similar to API References, Fern Docs can automatically generate your Webhook Reference documentation from your API definition. +Similar to API References, Fern Docs can automatically generate your webhook reference documentation from your API definition. Fern supports webhooks through: - **OpenAPI 3.1+**: Use the native `webhooks` field with an `operationId` (recommended) @@ -14,7 +14,9 @@ For more information on how to define webhooks, see: - [Webhooks in OpenAPI](../../openapi-definition/endpoints/webhooks) - [Webhooks in Fern Definition](../../fern-definition/webhooks) -Example: +## Configure your webhook reference + +Add a page title (`api`) and reference the name of the directory where your where your webhook definition is located (`api-name`). ```yml docs.yml {11-12} navigation: @@ -31,9 +33,9 @@ navigation: api-name: webhooks-v1 ``` -For a real-world example of webhook documentation generated from an API definition, check out [Webflow's Webhooks](https://developers.webflow.com/data/reference/webhooks/events/form-submission). +For a real-world example of webhook documentation generated from an API definition, check out [Webflow's webhooks](https://developers.webflow.com/data/reference/webhooks/events/form-submission). -### Directory Structure +### Directory structure Your webhooks should be defined in a dedicated folder within your Fern project: @@ -73,7 +75,7 @@ You can read more about how to define webhooks in your Fern Definition [here](/l -### Include more than one Webhook Reference +### Include more than one webhook reference To include multiple webhook definitions in your documentation, use the `webhook-name` property: ```yaml title="docs.yml" @@ -101,4 +103,32 @@ fern/ ### Create individual documentation pages for each webhook event - +To display each webhook event as an individual page with rich examples: + + + +Reference individual webhook pages using the `subpackage_{tag}.{webhook-event-name}` format, where: +- `{tag}` is the first tag (lowercase) from your webhook definition +- `{webhook-event-name}` is the `operationId` from your webhook definition + +```yaml title="docs.yml" +navigation: + - subpackage_plants.newPlantWebhook +``` + + + For OpenAPI, you must have the `tags` and `example` properties defined [in your webhook specification](/api-definitions/openapi/endpoints/webhooks). + + + + +Reference the individual webhook event using the `subpackage_{name}.{webhook-event-name}` format, where: +- `{name}` is the name of your API as defined in the `api.yml` file for your webhook definition. +- `{webhook-event-name}` is the identifier from your webhook definition + +```yaml title="docs.yml" +navigation: + - subpackage_api.newPlantWebhook +``` + + diff --git a/fern/snippets/individual-pages-webhook-ferndef.mdx b/fern/snippets/individual-pages-webhook-ferndef.mdx deleted file mode 100644 index 4c00c0e32..000000000 --- a/fern/snippets/individual-pages-webhook-ferndef.mdx +++ /dev/null @@ -1,15 +0,0 @@ -Reference individual webhook pages using the `subpackage_{api-name}.{webhook-name}`, where `api-name` is the name of the folder: -- `{folder-name}` is the first tag (lowercase) from your webhook definition -- `{webhook-event-name}` is the `operationId` from your webhook definition - -```yaml title="docs.yml" -navigation: - - subpackage_plants.newPlantWebhook -``` - -subpackage_webhooksv2_payInTransactionetc -subpackage_{api_name}.operationID - -operation id defines the webhook - -payload name defines the webhook for fern definition \ No newline at end of file diff --git a/fern/snippets/individual-pages-webhook-openapi.mdx b/fern/snippets/individual-pages-webhook-openapi.mdx deleted file mode 100644 index e3c5a5ffc..000000000 --- a/fern/snippets/individual-pages-webhook-openapi.mdx +++ /dev/null @@ -1,10 +0,0 @@ -To display each webhook event as an individual page with rich examples, you need to define `tags` and `example` [in your webhook specification](/api-definitions/openapi/endpoints/webhooks) (or [overrides file](/api-definitions/overview/overrides)). - -Then, reference individual webhook pages using the `subpackage_{tag}.{webhook-event-name}` format, where: -- `{tag}` is the first tag (lowercase) from your webhook definition -- `{webhook-event-name}` is the `operationId` from your webhook definition - -```yaml title="docs.yml" -navigation: - - subpackage_plants.newPlantWebhook -``` \ No newline at end of file