# 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>
  Fern recommends using [OpenAPI overlays](/api-definitions/openapi/overlays) instead of overrides for OpenAPI specs. Overlays follow the official [OpenAPI Overlay Specification](https://spec.openapis.org/overlay/v1.0.0.html) and are portable across different tools. Fern still supports OpenAPI overrides for backward compatibility.
</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:
      ...
```