Overlays | Fern Documentation

Overlays let you customize your OpenAPI specification without modifying the original file. This is useful when:

Your API specification is auto-generated from server code
You need different configurations for SDKs, documentation, or generated CLIs
You want to add Fern configurations like pagination or SDK method names
You want to make bulk changes across many endpoints using JSONPath wildcards

Overlays follow the OpenAPI Overlay Specification and are portable across the OpenAPI ecosystem.

Fern recommends using overlays instead of overrides for OpenAPI specs.

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).

Configure overlays

To use overlays, create an overlays file in the same folder as your spec and reference it in generators.yml:

generators.yml

api:
  specs:
    - openapi: openapi.json
      overlays: overlays.yml

Define the overlays file

Each action in an overlay targets elements using JSONPath and applies an update or remove operation:

openapi-overlays.yml

overlay: 1.0.0 # Required: Overlay Specification version
info:
  title: Customize Plant Store API # Required: Human-readable description of the overlay's purpose
  version: 1.0.0 # Required: Version identifier for tracking changes to this overlay
actions: # Required: Ordered list of changes to apply
  - target: $.info # JSONPath expression selecting the element to modify
    update: # Properties to merge with the targeted element
      x-fern-sdk-group-name: plants
  - target: $.paths['/plants/{plantId}'].get.parameters[?(@.name == 'plantId')]
    update:
      x-fern-parameter-name: id

Fern requires parentheses around JSONPath filter expressions. Use [?(@.name == 'plantId')] instead of [?@.name == 'plantId'].

Modifying OpenAPI properties

Use update to change standard OpenAPI properties like descriptions, summaries, or other fields:

openapi-overlays.yml

overlay: 1.0.0
info:
  title: Improve API documentation
  version: 1.0.0
actions:
  - target: $.paths['/plants'].get
    update:
      summary: List all available plants
      description: Returns a paginated list of plants in the store inventory.

Customizing with Fern extensions

Use update to add Fern extensions:

openapi-overlays.yml

overlay: 1.0.0
info:
  title: Add Fern SDK customizations
  version: 1.0.0
actions:
  # Add SDK group and method names
  - target: $.paths['/plants'].get
    update:
      x-fern-sdk-group-name: plants
      x-fern-sdk-method-name: list
  - target: $.paths['/plants'].post
    update:
      x-fern-sdk-group-name: plants
      x-fern-sdk-method-name: create
  # Rename a parameter
  - target: $.paths['/plants/{plantId}'].get.parameters[?(@.name == 'includeDetails')]
    update:
      x-fern-parameter-name: withDetails

Removing elements

Use remove: true to delete elements from your specification:

openapi-overlays.yml

overlay: 1.0.0
info:
  title: Remove internal endpoints
  version: 1.0.0
actions:
  - target: $.paths['/internal/debug']
    description: Remove debug endpoint from public SDK
    remove: true

Managing overlays across APIs

Each spec in generators.yml accepts one overlay file. You can reference the same file across specs or use separate files for different configurations.

Shared overlays across multiple specs

When multiple specs need the same customizations, point them to the same overlay file to avoid duplication:

generators.yml

api:
  specs:
    - openapi: ./payments-api.yml
      overlays: shared-overlays.yml       # Same overlay for both specs
    - openapi: ./users-api.yml
      overlays: shared-overlays.yml

If each spec needs unique customizations, create separate overlay files per spec:

generators.yml

api:
  specs:
    - openapi: ./payments-api.yml
      overlays: payments-overlays.yml
    - openapi: ./users-api.yml
      overlays: users-overlays.yml

Separate overlays for SDKs and docs

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

fern

fern.config.json

openapi.yml

docs

generators.yml

docs-overlays.yml

sdks

generators.yml

sdk-overlays.yml

sdks/generators.yml

api:
  specs:
    - openapi: ../openapi.yml
      overlays: sdk-overlays.yml

Overlays for different environments

Configure different overlays for production versus internal APIs:

generators.yml

groups:
  production:
    specs:
      - openapi: openapi.yml
        overlays: production-overlays.yml
    generators:
      ...
  internal:
    specs:
      - openapi: openapi.yml
        overlays: internal-overlays.yml
    generators:
      ...