Skip to content

Update overrides.mdx #523

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
merged 2 commits into from
Aug 20, 2025
Merged

Update overrides.mdx #523

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c68c6f7
Update overrides.mdx
mattblank11 Aug 20, 2025
79368ce
update wording around extensions
devalog Aug 20, 2025
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
16 changes: 10 additions & 6 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 @@ -3,13 +3,15 @@ title: Overrides
description: Customize your API definition using a separate overrides file.
---

Use an overrides file to customize your API definition without modifying the original spec. This is useful when:
Use an overrides file to customize your OpenAPI, AsyncAPI, OpenRPC, or gRPC 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, OpenRPC, and gRPC specifications. They are not needed for [Fern Definition](/api-definitions/ferndef/overview) since you can directly edit those files.

<Note>
While you can also embed Fern extensions directly in your API specification, using overrides files is the recommended approach as it keeps your original spec clean and separates concerns.
While you can also embed [Fern extensions](/api-definitions/overview/overrides#definition-specific-extensions) directly in your API specification, using overrides files is the recommended approach as it keeps your original spec clean and separates concerns.
</Note>

## Implement overrides
Expand All @@ -31,7 +33,9 @@ fern/
<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="Add customizations">
<Step title="Customize your spec with Fern extensions">

For OpenAPI, AsyncAPI, and OpenRPC, and gRPC, you can use [Fern's extensions](/api-definitions/overview/overrides#definition-specific-extensions) to apply customizations.

```yml title="overrides.yml" {4-5}
paths:
Expand Down Expand Up @@ -159,9 +163,9 @@ groups:
version: 0.8.8
```

## Definition-specific customizations
## Definition-specific extensions

Learn more about the customizations you can make for each definition:
Learn more about the Fern extensions you can use to customize your definition:

<CardGroup cols={2}>
<Card title="OpenAPI" href="/api-definitions/openapi/extensions/overview">
Expand All @@ -172,4 +176,4 @@ Learn more about the customizations you can make for each definition:
</Card>
<Card title="gRPC" href="/api-definitions/grpc/extensions/overview">
</Card>
</CardGroup>
</CardGroup>