(api definitions) Document headers in examples for Fern Definition and OpenAPI (#882)

Author: devalog

fern/products/api-def/ferndef-pages/api-yml/global-configuration.mdx

@@ -17,6 +17,8 @@ headers:
 ```
 </CodeBlock>
 
+When you define global headers in your `api.yml`, you must [include them in your endpoint examples](/api-definitions/ferndef/examples#examples-with-headers).
+
 ## Global path parameters
 
 You can specify path parameters that are meant to be included on every request:

fern/products/api-def/ferndef-pages/examples.mdx

@@ -315,6 +315,38 @@ errors:
     type: InsufficientFundsBody
 ```
 
+### Examples with headers
+
+When you have [global headers defined in your `api.yml`](/api-definitions/ferndef/api-yml/global-headers#global-headers), you must include them in your examples:
+
+```yml {15-16}
+service:
+  auth: true
+  base-path: ""
+  endpoints:
+    CreateShippingLabel:
+      docs: Create a new shipping label.
+      method: POST
+      path: /shipping
+      request: CreateShippingLabelRequest
+      response: ShippingLabel
+      errors:
+        - NotAuthorized
+        - InsufficientFunds
+      examples:
+        - headers:
+            X-App-Id: "app_12345"
+          request:
+            orderId: "online_789"
+            weightInOunces: 5
+          response:
+            body:
+              orderId: "online_789"
+              weightInOunces: 5
+              trackingNumber: "1Z26W8370303469306"
+              price: 2.50
+```
+
 ## Examples for path parameters
 
 ```yml

fern/products/api-def/openapi-pages/extensions/examples.mdx

@@ -9,13 +9,16 @@ you want to show more than one example in your documentation.
 
 `x-fern-examples` is an array of examples. Each element of the array
 can contain `path-parameters`, `query-parameters`, `request` and `response`
-examples values that are all associated.
+examples values that are all associated. If you [defined global headers via the `x-fern-global-headers` extension](/api-definitions/openapi/extensions/global-headers), you must include the headers in your examples. 
 
-```yaml title="openapi.yml" {5-16}
+```yaml title="openapi.yml" {5-19}
 paths:
   /users/{userId}:
     get:
       x-fern-examples:
+        - headers:
+            custom_api_key: "capi_12345" # header defined using x-global-header extension
+            userpool_id: "pool_67890"    # header defined using x-global-header extension
         - path-parameters:
             userId: user-1234
           response:

fern/products/api-def/openapi-pages/extensions/global-headers.mdx

@@ -33,3 +33,5 @@ class Client:
 
   def __init__(self, *, apiKey: str, userpoolId: typing.Optional[str])
 ```
+
+When you define global headers using `x-fern-global-headers`, you must [include them in your `x-fern-examples`](/api-definitions/openapi/extensions/request-response-examples).