🌿 Fern Scribe: Update readme and global header documentation. mak...

[github-actions]

🌿 Fern Scribe Documentation Update

Original Request: Update readme and global header documentation. make a new page in the deep dives section for readme and link to the reference documentation

Files Updated:

• fern/products/sdks/pages/reference/readme.mdx
• fern/products/sdks/sdks.yml
• fern/products/sdks/pages/deep-dives/readme.mdx
• fern/products/sdks/sdks.yml
• fern/products/sdks/reference/generators-yml-reference.mdx
• fern/products/sdks/guides/configure-global-headers.mdx
• fern/products/sdks/sdks.yml

Priority: Medium

Related Discussion: https://buildwithfern.slack.com/archives/C08T7EHDHMW/p1754058964789879

Additional Context: No response

⚠️ Files with MDX Validation Issues

The following files could not be updated due to MDX validation failures after 3 attempts:

1. /learn/openapi-definition/extensions/others (Other)

• URL: https://fern-api.docs.buildwithfern.com/learn/openapi-definition/extensions/others
• Validation Issues:
  • Mismatched CodeBlock tags: 1 opening, 0 closing

Suggested Content (needs manual MDX fixes):

---
title: Other extensions
description: Learn about Fern's OpenAPI extensions for authentication overrides, global headers, enum descriptions and names, audiences, and more.
---

Fern supports different OpenAPI extensions so that you can generate higher-quality SDKs.

## API version

You can define your API version scheme, such as a `X-API-Version` header. The supported versions and default value are specified like so:

```yaml title="openapi.yaml"
x-fern-version:
  version:
    header: X-API-Version
    default: "2.0.0"
    values:
      - "1.0.0"
      - "2.0.0"
      - "latest"
paths: ...

Global headers

Global headers can be configured in two ways:

1. In your OpenAPI specification using x-fern-global-headers
2. In your generators.yml configuration

OpenAPI Specification Method

To configure global headers in your OpenAPI spec, use the x-fern-global-headers extension:

x-fern-global-headers:
  - header: custom_api_key
    name: api_key
  - header: userpool_id
    optional: true

generators.yml Method

You can also specify global headers in your generators.yml:

api:
  - openapi: ./path/to/openapi
    headers:
      X-Version:
        name: version 
        type: literal<"1234">
      Authorization:
        name: apiKey
        type: string

The generated client will expose these headers in its constructor:

import os

class Client:
  def __init__(self, *, apiKey: str, version: str = "1234")

Fern will automatically detect headers used across multiple endpoints and mark them as global. You can override or add to these using either method above.

For more detailed information about configuring global headers, see our Global Headers deep dive.

Enum descriptions and names

OpenAPI doesn't natively support adding descriptions to enum values. To do this in Fern you can use the x-fern-enum
extension.

In the example below, we've added some descriptions to enum values. These descriptions will
propagate into the generated SDK and docs website.

components:
  schemas:
    CardSuit:
      enum:
        - clubs
        - diamonds
        - hearts
        - spades
      x-fern-enum:
        clubs:
          description: Some docs about clubs
        spades:
          description: Some docs about spades

x-fern-enum also supports a name field that allows you to customize the name of the enum in code.
This is particularly useful when you have enums that rely on symbolic characters that would otherwise cause
generated code not to compile.

For example, the following OpenAPI

components:
  schemas:
    Operand:
      enum:
        - '>'
        - '<'
      x-fern-enum:
        '>':
          name: GreaterThan
          description: Checks if value is greater than
        '<':
          name: LessThan
          description: Checks if value is less than

would generate

export enum Operand {
  GreaterThan = ">",
  LessThan = "<"
}

Schema names

OpenAPI allows you to define inlined schemas that do not have names.

components:
  schemas:
    Movie:
      type: object
      properties:
        name:
          type: string
        cast:
          type: array
          items:
            type: object
            properties:
              firstName:
                type: string
              lastName:
                type: string
              age:
                type: integer

Fern automatically generates names for all the inlined schemas. For example, in this example,
Fern would generate the name CastItem for the inlined array item schema.

export interface Movie {
  name?: string;
  cast?: CastItem[];
}

export interface CastItem {
  firstName?: string;
  lastName?: string;
  age?: i

... [Content truncated due to length]

2. /learn/sdks/deep-dives/configure-global-headers (Configure Global Headers)

• URL: https://fern-api.docs.buildwithfern.com/learn/sdks/deep-dives/configure-global-headers
• Validation Issues:
  • Mismatched Accordion tags: 4 opening, 3 closing

Suggested Content (needs manual MDX fixes):

---
title: Configure Global Headers
description: Guide to configuring global headers in your SDKs.
---

Your API may leverage certain headers for every endpoint or most endpoints.
These are called **global headers**.

## How it works for SDK users

Once you configure a global header (either automatically detected or manually
specified), Fern generates an SDK that accepts this as a constructor parameter.
Users can then provide the value once, and the generated SDK automatically
includes the header in all their API calls:

```python
import os

class Client:

  def __init__(self, *, apiKey: str):

Specifying global headers

Fern automatically identifies headers that are used in every request, or the
majority of requests, and marks them as global. You can configure global headers in three ways:

To specify headers that are meant to be included on every request:

```yaml {3} name: api headers: X-App-Id: string ```

Global path parameters

You can also specify path parameters that are meant to be included on every request:

```yaml name: api base-path: /{userId}/{orgId} path-parameters: userId: string orgId: string ```

Overriding the base path

If you have certain endpoints that do not live at the configured base-path, you can
override the base-path at the endpoint level.

service: 
  endpoints: 
    getMovie: 
      method: POST
      base-path: "override/{arg}"
      path: "movies/{movieId}"
      path-parameters: 
        arg: string

You cannot yet specify query parameters that are meant to be included on every request. If you'd like to see this feature, please upvote [this issue](https://github.com/fern-api/fern/issues/2930).

Use the x-fern-global-headers extension to label additional headers as global
or to alias the names of global headers:

x-fern-global-headers:
  - header: custom_api_key
    name: api_key
  - header: userpool_id
    optional: true

This configuration yields the following client:

import os

class Client:

  def __init__(self, *, apiKey: str, userpoolId: typing.Optional[str])

You can specify global headers in your generators.yml file using the headers configuration:

groups:
  publish:
    generators:
      - name: fernapi/fern-typescript-sdk
        version: 0.7.1
        output:
          location: npm
          package-name: '@fern-api/my-api'
          token: ${NPM_TOKEN}
        config:
          headers:
            X-Version:
              name: version # codegen name of the variable
              type: literal<"1234"> # type of the header, in this case a literal

This approach is particularly useful when you want to:

• Add headers that aren't defined in your OpenAPI spec
• Override header configurations from your API definition
• Specify headers specifically for SDK generation

When using `generators.yml` to configure headers, these settings will apply to all endpoints in the generated SDK.

Header Configuration Priority

When configuring global headers across multiple locations, the priority order is:

1. generators.yml configurations (highest priority)
2. OpenAPI/Fern Definition headers
3. Automatically detected headers (lowest priority)

If the same header is defined in multiple places, the configuration from the higher priority source will take precedence.

Best Practices

When configuring global headers:

• Use descriptive names that clearly indicate the header's purpose
• Consider making headers optional when appropriate
• Document any required header values in your SDK's README
• Use literal types for headers with fixed values
• Keep header configurations consis

... [Content truncated due to length]

**Note**: These files require manual review and correction of their MDX component structure before the content can be applied.

---
*This PR was automatically generated by Fern Scribe based on issue #323*

**Please review the changes carefully before merging.**

[devalog]

Originally, the doc was split between Fern Definition and OpenAPI. The slack thread clarified that they are actually two ways of setting global headers for OpenAPI. I'd expect Fern Scribe to expand the OpenAPI section to add the second option. Instead, it deleted the Fern Definition info and just said there are two ways to do global headers with OpenAPI:(

[devalog]

This is fine overall but rather long, especially the template variables section. I was hoping it would point to the existing reference documentation but it did not.

[devalog]

Created two new files:( Definitely overkill, a better option would be to make one new file and point to the existing reference documentation.

[devalog]

Wayyy too many edits to this document, and edits aren't even restricted to the headers and readme sections (already very defined)

[devalog]

Deleting lines that aren't at all related to the topic...

[devalog]

Overall, I found that this draft was too messy and random to even make a good starting point. I found it easier to start from scratch myself than try to edit this.

My own resulting PR for this topic: #325