***

title: Overrides
description: Customize your API definition using a separate overrides file.
---------------------------------------------------------------------------

For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see [https://buildwithfern.com/learn/llms.txt](https://buildwithfern.com/learn/llms.txt). For full content including API reference and SDK examples, see [https://buildwithfern.com/learn/llms-full.txt](https://buildwithfern.com/learn/llms-full.txt).

Use an overrides file to customize your OpenAPI, AsyncAPI, or OpenRPC definition without modifying the original spec. This is useful when:

* Your API specification is auto-generated from server code
* You need different configurations for SDKs versus documentation

Overrides are available for OpenAPI, AsyncAPI, and OpenRPC specifications. They're not needed for [Fern Definition](/api-definitions/ferndef/overview) since you can directly edit those files.

<Warning>
  For OpenAPI specs, Fern recommends using [overlays](/learn/api-definitions/openapi/overlays) instead of overrides. Overlays follow the official [OpenAPI Overlay Specification](https://spec.openapis.org/overlay/v1.0.0.html), support bulk changes with JSONPath wildcards, and are portable across the OpenAPI ecosystem.

  Overrides are also fully supported. If overrides are working for your team, there's no need to switch. You can also use both together (overrides are applied first, then overlays).
</Warning>

## Implement overrides

<Steps>
  <Step title="Create an overrides file">
    [Create an `overrides.yml` file](/cli-api-reference/cli-reference/commands#fern-write-overrides) in the folder that contains your API definition:

    ```bash {6}
    fern/
      ├─ fern.config.json 
      ├─ generators.yml
      └─ spec-folder/
        ├─ spec-file.yml # API definition
        └─ overrides.yml
    ```

    <Note>
       The format of the overrides file is independent from the spec. For example, even if your OpenAPI spec is in JSON format, you can write the overrides in yaml. 
    </Note>
  </Step>

  <Step title="Customize your spec with Fern extensions">
    For OpenAPI, AsyncAPI, and OpenRPC, you can use [Fern's extensions](/learn/api-definitions/asyncapi/overrides#definition-specific-extensions) to apply customizations.

    ```yml title="overrides.yml" {4-5}
    paths: 
     /users: 
       post: 
        x-fern-sdk-group-name: users
        x-fern-sdk-method-name: create
    ```
  </Step>

  <Step title="Add a reference to generators.yml">
    ```yaml title="generators.yml"
    api:
      specs:
        - openapi: spec-file.yml 
          overrides: ./overrides.yml
    ```

    You can also specify [multiple override files](#multiple-override-files).
  </Step>

  <Step title="Fern combines your spec and overrides">
    Now when you run `fern generate`, Fern combines your original API specification with the overrides file:

    <CodeGroup>
      ```yml openapi.yml
      paths: 
       /users: 
         post: 
          description: Create a User
          operationId: users_post
          requestBody: 
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/User'
      ```

      ```yml title="overrides.yml" {4-5}
      paths: 
       /users: 
         post: 
          x-fern-sdk-group-name: users
          x-fern-sdk-method-name: create
      ```

      ```yml title="combined" {4-5}
      paths: 
       /users/post: 
        post: 
          x-fern-sdk-group-name: users
          x-fern-sdk-method-name: create      
          description: Create a User
          operationId: users_post
          requestBody: 
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/User'   
      ```
    </CodeGroup>
  </Step>
</Steps>

## Managing overrides across APIs

The `overrides` field accepts a single path or a list of paths. When multiple paths are provided, overrides are applied sequentially in order, with later files taking precedence over earlier ones for conflicting keys.

<AccordionGroup>
  <Accordion title="Shared overrides across multiple specs">
    When your project has multiple specs that need the same foundational overrides, use a shared base file and layer spec-specific overrides on top. This avoids duplicating common overrides (e.g., SDK method names or authentication extensions) across each spec:

    ```yaml title="generators.yml"
    api:
      specs:
        - openapi: ./payments-api.yml
          overrides:
            - ./shared-overrides.yml       # Common overrides for all specs
            - ./payments-overrides.yml     # Payments-specific overrides
        - openapi: ./users-api.yml
          overrides:
            - ./shared-overrides.yml       # Same common overrides
            - ./users-overrides.yml        # Users-specific overrides
    ```
  </Accordion>

  <Accordion title="Separate overrides for SDKs and docs">
    When you need entirely different overrides for SDK generation versus documentation, use separate folders with their own `generators.yml`. Each folder references only the overrides relevant to its concern:

    <Files>
      <Folder name="fern" defaultOpen>
        <File name="fern.config.json" />

        <File name="openapi.yml" />

        <Folder name="docs" defaultOpen>
          <File name="generators.yml" />

          <File name="docs-overrides.yml" />
        </Folder>

        <Folder name="sdks" defaultOpen>
          <File name="generators.yml" />

          <File name="sdk-overrides.yml" />
        </Folder>
      </Folder>
    </Files>

    ```yaml title="sdks/generators.yml"
    api:
      specs:
        - openapi: ../openapi.yml
          overrides: sdk-overrides.yml
    ```

    If the SDK and docs overrides share a common base, you can use multiple override files within each folder to avoid duplication:

    ```yaml title="sdks/generators.yml"
    api:
      specs:
        - openapi: ../openapi.yml
          overrides:
            - ../shared-overrides.yml      # Common overrides for both SDKs and docs
            - sdk-overrides.yml            # SDK-specific overrides
    ```
  </Accordion>

  <Accordion title="Overrides for different environments">
    When your public and internal APIs share the same spec but need different overrides, use multiple override files to layer internal-specific additions on top of the public base. This is especially useful when the internal API is a superset of the public API:

    ```yaml title="generators.yml" {5, 12-13}
    groups:
      public:
        specs:
          - openapi: openapi.yml
            overrides: public-overrides.yml
        generators:
          ...
      internal:
        specs:
          - openapi: openapi.yml
            overrides:
              - public-overrides.yml           # Base: all public overrides
              - internal-overrides.yml         # Additional: internal-only overrides
        generators:
          ...
    ```

    This avoids duplicating the public overrides in the internal configuration. The `internal-overrides.yml` file only needs to contain the additions specific to the internal API.
  </Accordion>
</AccordionGroup>