Document how to create individual pages for webhook events (Docs) (#594)

Author: devalog

fern/products/api-def/openapi-pages/webhooks.mdx

@@ -12,17 +12,60 @@ Fern supports two methods for defining webhooks in your OpenAPI specification:
 
 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.
 
-```yaml openapi.yml {4}
+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:
     post:
-      operationId: newPlantWebhook
+      operationId: newPlantWebhook # Defines webhook
+      summary: New Plant Added
+      description: Information about a new plant that was added to the store
+      tags:
+        - Plants # Creates dedicated page
       requestBody:
-        description: Information about a new Plant in the system
+        description: The plant data when a new plant is added
         content:
           application/json:
             schema:
-              $ref: '#/components/schemas/Plant'
+              description: The Webhook payload for when a new plant is added to the store
+              properties:
+                triggerType:
+                  description: The type of event that triggered the request
+                  type: string
+                  example: "new_plant"
+                payload:
+                  type: object
+                  description: The payload of data sent from the plant store
+                  properties:
+                    plantId:
+                      type: string
+                      description: The unique identifier for the plant
+                      example: "64f1a2b3c5d6e7f8a9b0c1d2"
+                    name:
+                      type: string
+                      description: The name of the plant
+                      example: "Monstera Deliciosa"
+                    price:
+                      type: number
+                      format: float
+                      description: The price of the plant in dollars
+                      example: 29.99
+                    addedAt:
+                      type: string
+                      format: date-time
+                      description: The timestamp when the plant was added
+                      example: "2024-01-15T10:30:00.000Z"
+              example: # Full payload example for docs
+                triggerType: "new_plant"
+                payload:
+                  plantId: "64f1a2b3c5d6e7f8a9b0c1d2"
+                  name: "Monstera Deliciosa"
+                  price: 29.99
+                  addedAt: "2024-01-15T10:30:00.000Z"
       responses:
         '200':
           description: Return a 200 status to indicate that the data was received successfully
@@ -32,13 +75,20 @@ webhooks:
 
 For OpenAPI 3.0, use the `x-fern-webhook: true` extension to define webhooks. Fern will treat the `requestBody` as the webhook payload.
 
-```yaml openapi.yml {6}
+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/: 
     post: 
       summary: Payment Initiated
       operationId: initiatePayment
-      x-fern-webhook: true
+      tags:
+        - Payments # Creates dedicated page
+      x-fern-webhook: true # Defines webhooks
       requestBody:
         content:
           application/json:
@@ -47,11 +97,15 @@ paths:
               properties:
                 amount:
                   type: number
+                  example: 99.99
                 currency:
                   $ref: '#/components/schemas/Currency'
               required:
                 - amount
-                - currency 
+                - currency
+              example: # Full payload example for docs
+                amount: 99.99
+                currency: "USD"
 ```
 
 <Info> 

fern/products/docs/pages/api-references/generate-webhook-ref.mdx

@@ -98,3 +98,16 @@ fern/
           │   └── openapi.yml   # Order webhook OpenAPI spec
           └── generators.yml
 ```
+
+### Create individual documentation pages for each webhook event (OpenAPI)
+
+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
+```