OpenAPI

Overlays

View as Markdown

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 versus documentation
  • You want to add Fern configurations like pagination or SDK method names

Overlays follow the OpenAPI Overlay Specification.

Fern recommends using OpenAPI overlays instead of overrides for OpenAPI specs. Overlays follow the official OpenAPI Overlay Specification and are portable across different tools.

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

Configure overlays

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

generators.yml
1api:
2  specs:
3    - openapi: openapi.json
4      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
1overlay: 1.0.0 # Required: Overlay Specification version
2info:
3  title: Customize Plant Store API # Required: Human-readable description of the overlay's purpose
4  version: 1.0.0 # Required: Version identifier for tracking changes to this overlay
5actions: # Required: Ordered list of changes to apply
6  - target: $.info # JSONPath expression selecting the element to modify
7    update: # Properties to merge with the targeted element
8      x-fern-sdk-group-name: plants
9  - target: $.paths['/plants/{plantId}'].get.parameters[?(@.name == 'plantId')]
10    update:
11      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
1overlay: 1.0.0
2info:
3  title: Improve API documentation
4  version: 1.0.0
5actions:
6  - target: $.paths['/plants'].get
7    update:
8      summary: List all available plants
9      description: Returns a paginated list of plants in the store inventory.

Customizing with Fern extensions

Use update to add Fern extensions:

openapi-overlays.yml
1overlay: 1.0.0
2info:
3  title: Add Fern SDK customizations
4  version: 1.0.0
5actions:
6  # Add SDK group and method names
7  - target: $.paths['/plants'].get
8    update:
9      x-fern-sdk-group-name: plants
10      x-fern-sdk-method-name: list
11  - target: $.paths['/plants'].post
12    update:
13      x-fern-sdk-group-name: plants
14      x-fern-sdk-method-name: create
15  # Rename a parameter
16  - target: $.paths['/plants/{plantId}'].get.parameters[?(@.name == 'includeDetails')]
17    update:
18      x-fern-parameter-name: withDetails

Removing elements

Use remove: true to delete elements from your specification:

openapi-overlays.yml
1overlay: 1.0.0
2info:
3  title: Remove internal endpoints
4  version: 1.0.0
5actions:
6  - target: $.paths['/internal/debug']
7    description: Remove debug endpoint from public SDK
8    remove: true

Separate overlays for SDKs and docs

Use different overlays 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
1api:
2  specs:
3    - openapi: ../openapi.yml
4      overlays: sdk-overlays.yml

Overlays for different environments

Configure different overlays for production versus internal APIs:

generators.yml
1groups:
2  production:
3    specs:
4      - openapi: openapi.yml
5        overlays: production-overlays.yml
6    generators:
7      ...
8  internal:
9    specs:
10      - openapi: openapi.yml
11        overlays: internal-overlays.yml
12    generators:
13      ...