From 65606401fd24e6b50fd26df51d7f9d1f4f77f5c9 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Thu, 18 Sep 2025 16:41:59 -0400 Subject: [PATCH 1/2] add info about adding headers to examples --- .../api-yml/global-configuration.mdx | 2 ++ .../api-def/ferndef-pages/examples.mdx | 32 +++++++++++++++++++ .../openapi-pages/extensions/examples.mdx | 7 ++-- .../extensions/global-headers.mdx | 2 ++ 4 files changed, 41 insertions(+), 2 deletions(-) diff --git a/fern/products/api-def/ferndef-pages/api-yml/global-configuration.mdx b/fern/products/api-def/ferndef-pages/api-yml/global-configuration.mdx index 0f3cc3b7d..a48b8f10f 100644 --- a/fern/products/api-def/ferndef-pages/api-yml/global-configuration.mdx +++ b/fern/products/api-def/ferndef-pages/api-yml/global-configuration.mdx @@ -17,6 +17,8 @@ headers: ``` +When you define global headers in your `api.yml`, you must [include them in your endpoint examples](/api-definitions/ferndef/examples#examples-with-headers) to pass validation. + ## Global path parameters You can specify path parameters that are meant to be included on every request: diff --git a/fern/products/api-def/ferndef-pages/examples.mdx b/fern/products/api-def/ferndef-pages/examples.mdx index b16ab4936..d513b1d52 100644 --- a/fern/products/api-def/ferndef-pages/examples.mdx +++ b/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 need to include them in your endpoint examples to pass validation: + +```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 diff --git a/fern/products/api-def/openapi-pages/extensions/examples.mdx b/fern/products/api-def/openapi-pages/extensions/examples.mdx index 4cb471d59..f99f07544 100644 --- a/fern/products/api-def/openapi-pages/extensions/examples.mdx +++ b/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: diff --git a/fern/products/api-def/openapi-pages/extensions/global-headers.mdx b/fern/products/api-def/openapi-pages/extensions/global-headers.mdx index 254c27715..f329e065e 100644 --- a/fern/products/api-def/openapi-pages/extensions/global-headers.mdx +++ b/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). \ No newline at end of file From c5f7e2ba35dc967b1b9b400f23d5b6db05470c19 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Thu, 18 Sep 2025 16:46:41 -0400 Subject: [PATCH 2/2] wording fix --- .../api-def/ferndef-pages/api-yml/global-configuration.mdx | 2 +- fern/products/api-def/ferndef-pages/examples.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/fern/products/api-def/ferndef-pages/api-yml/global-configuration.mdx b/fern/products/api-def/ferndef-pages/api-yml/global-configuration.mdx index a48b8f10f..995e02d4d 100644 --- a/fern/products/api-def/ferndef-pages/api-yml/global-configuration.mdx +++ b/fern/products/api-def/ferndef-pages/api-yml/global-configuration.mdx @@ -17,7 +17,7 @@ headers: ``` -When you define global headers in your `api.yml`, you must [include them in your endpoint examples](/api-definitions/ferndef/examples#examples-with-headers) to pass validation. +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 diff --git a/fern/products/api-def/ferndef-pages/examples.mdx b/fern/products/api-def/ferndef-pages/examples.mdx index d513b1d52..666e45e75 100644 --- a/fern/products/api-def/ferndef-pages/examples.mdx +++ b/fern/products/api-def/ferndef-pages/examples.mdx @@ -317,7 +317,7 @@ errors: ### Examples with headers -When you have [global headers defined in your `api.yml`](/api-definitions/ferndef/api-yml/global-headers#global-headers), you need to include them in your endpoint examples to pass validation: +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: