# Overrides

> Customize your API definition using a separate overrides file.

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 are 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) and are portable across different tools.

  However, overrides are also fully supported. If your team already uses overrides, there's no need to switch unless you need advanced functionality. 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](/api-definitions/overview/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
    ```
  </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>

## Separate overrides for SDKs and docs

Use different overrides files for SDK generation versus documentation by creating separate folders with their own `generators.yml`:

```bash
fern/
  ├─ fern.config.json
  ├─ openapi.yml
  ├─ docs/
  │   ├─ generators.yml
  │   └─ docs-overrides.yml
  └─ sdks/
      ├─ generators.yml
      └─ sdk-overrides.yml
```

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

## Overrides for different environments

Configure different overrides for production versus internal APIs:

```yaml title="generators.yml"
groups:
  production:
    specs:
      - openapi: openapi.yml
        overrides: production-overrides.yml
    generators:
      ...
  internal:
    specs:
      - openapi: openapi.yml
        overrides: internal-overrides.yml
    generators:
      ...
```