Skip to content

docs: clarify that overrides are fully supported alongside overlays #3333

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
devalog merged 3 commits into from
Jan 28, 2026
+6 −4
Merged

docs: clarify that overrides are fully supported alongside overlays #3333

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
9dcebc1
docs: clarify that overrides are fully supported alongside overlays
fern-support Jan 28, 2026
19fb1a8
clarify note
devalog Jan 28, 2026
a3db6ba
cut a few words
devalog Jan 28, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions fern/products/api-def/openapi-pages/overlays.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,9 +12,9 @@ Overlays let you customize your OpenAPI specification without modifying the orig
Overlays follow the [OpenAPI Overlay Specification](https://spec.openapis.org/overlay/v1.0.0.html).

<Note>
Overlays are the recommended approach for customizing OpenAPI specifications. Compared to [overrides](/api-definitions/overview/overrides), overlays offer additional capabilities like bulk modifications using JSONPath wildcards and the ability to modify elements within arrays.
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 overrides for backward compatibility.
[Overrides](/api-definitions/overview/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).
</Note>

## Configure overlays
Expand Down
6 changes: 4 additions & 2 deletions fern/products/api-def/pages/overrides.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,9 @@ Use an overrides file to customize your OpenAPI, AsyncAPI, or OpenRPC definition
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.
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
Expand Down Expand Up @@ -102,4 +104,4 @@ paths:

## Overrides for different environments

<Markdown src="/snippets/different-environments.mdx" type="overrides" />
<Markdown src="/snippets/different-environments.mdx" type="overrides" />
Loading