diff --git a/fern/docs.yml b/fern/docs.yml
index b97784f87..d5ee58ddf 100644
--- a/fern/docs.yml
+++ b/fern/docs.yml
@@ -495,6 +495,18 @@ redirects:
- source: /learn/openapi-definition/extensions/webhooks
destination: /learn/api-definitions/openapi/endpoints/webhooks
permanent: true
+ - source: /learn/api-definitions/openapi/overlay-customizations
+ destination: /learn/api-definitions/overview/overrides
+ permanent: true
+ - source: /learn/api-definitions/asyncapi/overlay-customizations
+ destination: /learn/api-definitions/overview/overrides
+ permanent: true
+ - source: /learn/api-definitions/openrpc/overlay-customizations
+ destination: /learn/api-definitions/overview/overrides
+ permanent: true
+ - source: /learn/api-definitions/grpc/overlay-customizations
+ destination: /learn/api-definitions/overview/overrides
+ permanent: true
# API Definition Fern specific redirects first
- source: /learn/api-definition/fern/endpoints/:slug*
diff --git a/fern/products/api-def/api-def.yml b/fern/products/api-def/api-def.yml
index a1c2a90ea..7bf18fde6 100644
--- a/fern/products/api-def/api-def.yml
+++ b/fern/products/api-def/api-def.yml
@@ -5,6 +5,8 @@ navigation:
path: ./pages/what-is-an-api-definition.mdx
- page: Project structure
path: ./pages/project-structure.mdx
+ - page: Overrides
+ path: ./pages/overrides.mdx
- section: OpenAPI
collapsed: true
slug: openapi
@@ -15,8 +17,6 @@ navigation:
path: ./openapi-pages/auth.mdx
- page: Servers
path: ./openapi-pages/servers.mdx
- - page: Automation
- path: ./openapi-pages/automation.mdx
slug: sync-your-open-api-specification
- section: Endpoints
slug: endpoints
@@ -63,7 +63,12 @@ navigation:
- page: Schema names
path: ./openapi-pages/extensions/schema-names.mdx
- page: Server names
- path: ./openapi-pages/extensions/server-names.mdx
+ path: ./openapi-pages/extensions/server-names.mdx
+ - section: Workflow & automation
+ skip-slug: true
+ contents:
+ - page: Sync your OpenAPI specification
+ path: ./openapi-pages/automation.mdx
- section: Integrate your server framework
slug: frameworks
contents:
@@ -123,8 +128,6 @@ navigation:
- section: Workflow & automation
skip-slug: true
contents:
- - page: Overlay customizations
- path: ./asyncapi-pages/overrides.mdx
- page: Sync your AsyncAPI specification
path: ./asyncapi-pages/automation.mdx
- section: OpenRPC
@@ -186,8 +189,6 @@ navigation:
- section: Workflow & automation
skip-slug: true
contents:
- - page: Overlay customizations
- path: ./openrpc-pages/overrides.mdx
- page: Sync your OpenRPC specification
path: ./openrpc-pages/automation.mdx
- section: gRPC
@@ -253,8 +254,6 @@ navigation:
- section: Workflow & automation
skip-slug: true
contents:
- - page: Overlay customizations
- path: ./grpc-pages/overrides.mdx
- page: Sync your gRPC specification
path: ./grpc-pages/automation.mdx
- section: Fern Definition
diff --git a/fern/products/api-def/asyncapi-pages/extensions/overview.md b/fern/products/api-def/asyncapi-pages/extensions/overview.md
index dbc67bd18..39c7be3c6 100644
--- a/fern/products/api-def/asyncapi-pages/extensions/overview.md
+++ b/fern/products/api-def/asyncapi-pages/extensions/overview.md
@@ -3,7 +3,9 @@ title: Overview of AsyncAPI extensions
description: Learn about Fern's AsyncAPI extensions for generating higher-quality SDKs
---
-Fern supports a variety of AsyncAPI extensions that enhance your API specification and generate higher-quality SDKs. You can apply these extensions in two ways: by overlaying them in separate override files or by embedding them directly in your AsyncAPI specification.
+Fern supports a variety of AsyncAPI extensions that enhance your API specification and generate higher-quality SDKs.
+
+You can apply these extensions in two ways: by overlaying them in separate override files or by embedding them directly in your AsyncAPI specification. See [Overrides](/api-definitions/overview/overrides) for more information.
## Available extensions
@@ -22,6 +24,4 @@ The table below shows all available extensions and links to detailed documentati
If there's an extension you want that doesn't already exist, file an [issue](https://github.com/fern-api/fern/issues/new) to start a discussion about it.
-
-
-
\ No newline at end of file
+
\ No newline at end of file
diff --git a/fern/products/api-def/asyncapi-pages/overrides.mdx b/fern/products/api-def/asyncapi-pages/overrides.mdx
deleted file mode 100644
index 0e76d5f18..000000000
--- a/fern/products/api-def/asyncapi-pages/overrides.mdx
+++ /dev/null
@@ -1,168 +0,0 @@
----
-title: Overlay Customizations
-subtitle: Use overlay files to modify your AsyncAPI specification without editing the original
----
-
-Overlays allow you to modify your AsyncAPI specification without directly editing the original file. This is useful for:
-- Adding Fern-specific extensions
-- Customizing documentation
-- Adding examples and descriptions
-- Overriding specific properties
-
-## Configure overlays
-
-To use overlays, add them to your `generators.yml` file:
-
-```yaml title="generators.yml" {3-5}
-api:
- specs:
- - spec: asyncapi.yml
- overlays:
- - overlay.yml
- generators:
- - name: fernapi/fern-typescript-node-sdk
- version: 0.8.8
-```
-
-## Overlay file structure
-
-Overlay files follow the [OpenAPI Overlay Specification](https://spec.openapis.org/overlay/v1.0.0) format:
-
-```yaml title="overlay.yml"
-overlay: 1.0.0
-info:
- title: AsyncAPI Fern Extensions
- version: 1.0.0
-actions:
- - target: $.operations.sendNotification
- update:
- x-fern-sdk-method-name: notify
- summary: Send a notification to a user
- - target: $.channels['user/events']
- update:
- description: Channel for user-related events
- x-fern-audiences:
- - public
-```
-
-## Add method names
-
-Override SDK method names for better developer experience:
-
-```yaml title="overlay.yml" {7-9}
-overlay: 1.0.0
-info:
- title: SDK Method Names
- version: 1.0.0
-actions:
- - target: $.operations.subscribeToUserEvents
- update:
- x-fern-sdk-method-name: onUserEvent
- summary: Subscribe to user events with callback
- - target: $.operations.publishOrderUpdate
- update:
- x-fern-sdk-method-name: updateOrder
- summary: Publish order status update
-```
-
-## Add examples
-
-Enhance your specification with examples:
-
-```yaml title="overlay.yml" {7-17}
-overlay: 1.0.0
-info:
- title: Message Examples
- version: 1.0.0
-actions:
- - target: $.components.messages.UserSignup
- update:
- examples:
- - name: StandardSignup
- summary: Regular user signup
- payload:
- id: "user_123"
- email: "john@example.com"
- name: "John Doe"
- signupSource: "web"
- timestamp: "2024-01-15T10:30:00Z"
-```
-
-## Filter with audiences
-
-Add audience filtering to operations and channels:
-
-```yaml title="overlay.yml" {7-9, 12-14}
-overlay: 1.0.0
-info:
- title: Audience Filtering
- version: 1.0.0
-actions:
- - target: $.operations.adminAlert
- update:
- x-fern-audiences:
- - admin
- - target: $.channels['internal/debug']
- update:
- x-fern-audiences:
- - internal
-```
-
-## Add documentation
-
-Enhance descriptions and documentation:
-
-```yaml title="overlay.yml" {7-11}
-overlay: 1.0.0
-info:
- title: Enhanced Documentation
- version: 1.0.0
-actions:
- - target: $.operations.sendMessage
- update:
- description: |
- Send a message to the specified channel. This operation supports
- real-time delivery with automatic retry on failure. Messages are
- guaranteed to be delivered at least once.
- summary: Send message with delivery guarantees
-```
-
-## Server configurations
-
-Add server-specific configurations:
-
-```yaml title="overlay.yml" {7-11}
-overlay: 1.0.0
-info:
- title: Server Extensions
- version: 1.0.0
-actions:
- - target: $.servers.production
- update:
- x-fern-server-name: Production
- description: Production environment with high availability
- bindings:
- ws:
- headers:
- type: object
- properties:
- X-API-Version:
- type: string
- const: "v1"
-```
-
-## Multiple overlays
-
-You can apply multiple overlay files in sequence:
-
-```yaml title="generators.yml" {4-7}
-api:
- specs:
- - spec: asyncapi.yml
- overlays:
- - base-overlay.yml
- - sdk-overlay.yml
- - docs-overlay.yml
-```
-
-Overlays are applied in order, allowing you to build up customizations incrementally while keeping your original AsyncAPI specification clean and focused.
\ No newline at end of file
diff --git a/fern/products/api-def/grpc-pages/extensions/overview.md b/fern/products/api-def/grpc-pages/extensions/overview.md
index c275ffcb3..3ca0fbbe6 100644
--- a/fern/products/api-def/grpc-pages/extensions/overview.md
+++ b/fern/products/api-def/grpc-pages/extensions/overview.md
@@ -5,6 +5,8 @@ description: Learn about Fern's gRPC extensions for generating higher-quality SD
Fern supports a variety of gRPC extensions that enhance your API specification and generate higher-quality SDKs.
+You can apply these extensions in two ways: by overlaying them in separate override files or by embedding them directly in your gRPC specification. See [Overrides](/api-definitions/overview/overrides) for more information.
+
## Available extensions
The table below shows all available extensions and links to detailed documentation for each one.
diff --git a/fern/products/api-def/grpc-pages/overrides.mdx b/fern/products/api-def/grpc-pages/overrides.mdx
deleted file mode 100644
index beda30a91..000000000
--- a/fern/products/api-def/grpc-pages/overrides.mdx
+++ /dev/null
@@ -1,432 +0,0 @@
----
-title: Overlay Customizations
-subtitle: Use overlay files to modify your gRPC specifications without editing the original Proto files
----
-
-Overlays allow you to modify your gRPC specifications without directly editing the original Protocol Buffer files. This is useful for:
-- Adding Fern-specific extensions
-- Customizing SDK method and parameter names
-- Adding examples and documentation
-- Configuring audiences and filtering
-
-## Configure overlays
-
-To use overlays, add them to your `generators.yml` file:
-
-```yaml title="generators.yml" {3-5}
-api:
- specs:
- - spec: proto/user_service.proto
- overlays:
- - overlay.yml
- generators:
- - name: fernapi/fern-typescript-node-sdk
- version: 0.8.8
-```
-
-## Overlay file structure
-
-Overlay files use Protocol Buffer text format with Fern extensions:
-
-```protobuf title="overlay.yml"
-# Add SDK method names to existing gRPC methods
-service UserService {
- rpc CreateUser {
- option (x_fern_sdk_method_name) = "create";
- }
-
- rpc GetUser {
- option (x_fern_sdk_method_name) = "get";
- }
-
- rpc ListUsers {
- option (x_fern_sdk_method_name) = "list";
- option (x_fern_pagination) = '{
- "cursor": "page_token",
- "results": "users",
- "next_cursor": "next_page_token"
- }';
- }
-}
-```
-
-## Add method names
-
-Override SDK method names for better developer experience:
-
-```protobuf title="overlay.yml"
-service UserService {
- rpc GetUserById {
- option (x_fern_sdk_method_name) = "getUser";
- }
-
- rpc CreateNewUser {
- option (x_fern_sdk_method_name) = "create";
- }
-
- rpc UpdateUserProfile {
- option (x_fern_sdk_method_name) = "updateProfile";
- }
-
- rpc DeleteUserAccount {
- option (x_fern_sdk_method_name) = "delete";
- }
-}
-
-service AuthenticationService {
- option (x_fern_sdk_service_name) = "auth";
-
- rpc LoginUser {
- option (x_fern_sdk_method_name) = "login";
- }
-
- rpc LogoutUser {
- option (x_fern_sdk_method_name) = "logout";
- }
-}
-```
-
-## Add parameter names
-
-Customize parameter names for better SDK ergonomics:
-
-```protobuf title="overlay.yml"
-message CreateUserRequest {
- string email_address {
- option (x_fern_parameter_name) = "email";
- }
-
- string full_name {
- option (x_fern_parameter_name) = "name";
- }
-
- int32 age_in_years {
- option (x_fern_parameter_name) = "age";
- }
-
- UserPreferences user_preferences {
- option (x_fern_parameter_name) = "preferences";
- }
-}
-
-message User {
- string user_id {
- option (x_fern_parameter_name) = "id";
- }
-
- google.protobuf.Timestamp created_timestamp {
- option (x_fern_parameter_name) = "createdAt";
- }
-
- google.protobuf.Timestamp updated_timestamp {
- option (x_fern_parameter_name) = "updatedAt";
- }
-}
-```
-
-## Add examples
-
-Enhance your specification with comprehensive examples:
-
-```protobuf title="overlay.yml"
-service UserService {
- rpc CreateUser {
- option (x_fern_examples) = '{
- "StandardUser": {
- "description": "Create a regular user account",
- "request": {
- "email": "john@example.com",
- "name": "John Doe",
- "age": 30,
- "preferences": {
- "theme": "dark",
- "notifications": true
- }
- },
- "response": {
- "id": "user_123",
- "email": "john@example.com",
- "name": "John Doe",
- "created_at": "2024-01-15T10:30:00Z"
- }
- },
- "AdminUser": {
- "description": "Create an admin user with permissions",
- "request": {
- "email": "admin@example.com",
- "name": "Admin User",
- "role": "admin",
- "permissions": ["read", "write", "delete"]
- },
- "response": {
- "id": "user_456",
- "email": "admin@example.com",
- "name": "Admin User",
- "role": "admin",
- "created_at": "2024-01-15T10:30:00Z"
- }
- }
- }';
- }
-}
-```
-
-## Filter with audiences
-
-Add audience filtering to services and methods:
-
-```protobuf title="overlay.yml"
-service UserService {
- option (x_fern_audiences) = "public";
-
- rpc GetUser {
- option (x_fern_audiences) = "public";
- }
-
- rpc CreateUser {
- option (x_fern_audiences) = "public";
- }
-}
-
-service AdminService {
- option (x_fern_audiences) = "admin";
-
- rpc ListAllUsers {
- option (x_fern_audiences) = "admin";
- }
-
- rpc DeleteUser {
- option (x_fern_audiences) = "admin";
- }
-}
-
-service DebugService {
- option (x_fern_audiences) = "internal";
-
- rpc GetSystemInfo {
- option (x_fern_audiences) = "internal";
- }
-}
-```
-
-## Add error handling
-
-Configure custom error handling for methods:
-
-```protobuf title="overlay.yml"
-service UserService {
- rpc CreateUser {
- option (x_fern_error_handling) = '{
- "ALREADY_EXISTS": {
- "error_name": "UserAlreadyExistsError",
- "user_friendly_message": "A user with this email already exists"
- },
- "INVALID_ARGUMENT": {
- "error_name": "ValidationError",
- "user_friendly_message": "Please check your input and try again"
- },
- "RESOURCE_EXHAUSTED": {
- "error_name": "RateLimitError",
- "retry_after_seconds": 60
- }
- }';
- }
-
- rpc ProcessPayment {
- option (x_fern_retry) = '{
- "max_attempts": 3,
- "exponential_backoff": true,
- "initial_delay_ms": 1000,
- "max_delay_ms": 30000
- }';
- }
-}
-```
-
-## Add documentation
-
-Enhance descriptions and documentation:
-
-```protobuf title="overlay.yml"
-service UserService {
- option (x_fern_service_description) = "User management service for creating, updating, and managing user accounts with comprehensive authentication and profile management capabilities.";
-
- rpc CreateUser {
- option (x_fern_method_description) = "Create a new user account with email verification and automatic profile setup. Supports custom preferences and role assignment.";
- }
-
- rpc GetUser {
- option (x_fern_method_description) = "Retrieve user information by ID with optional inclusion of profile data, preferences, and activity history.";
- }
-
- rpc UpdateUser {
- option (x_fern_method_description) = "Update user profile information with field-level updates using Protocol Buffer field masks for efficient partial updates.";
- }
-}
-```
-
-## Configure timeouts and retries
-
-Add timeout and retry configurations:
-
-```protobuf title="overlay.yml"
-service UserService {
- rpc GenerateUserReport {
- option (x_fern_timeout) = '{
- "seconds": 300,
- "description": "Report generation can take up to 5 minutes for large datasets"
- }';
- }
-
- rpc QuickUserLookup {
- option (x_fern_timeout) = '{
- "seconds": 5,
- "description": "Quick lookup operations should complete within 5 seconds"
- }';
- }
-
- rpc ImportUsers {
- option (x_fern_retry) = '{
- "max_attempts": 5,
- "exponential_backoff": true,
- "initial_delay_ms": 2000,
- "max_delay_ms": 60000,
- "retry_on_status": ["UNAVAILABLE", "DEADLINE_EXCEEDED", "INTERNAL"]
- }';
- }
-}
-```
-
-## Streaming configurations
-
-Configure streaming methods:
-
-```protobuf title="overlay.yml"
-service UserStreamingService {
- rpc StreamUserEvents {
- option (x_fern_streaming) = '{
- "type": "server_streaming",
- "termination": "client_closes",
- "description": "Real-time stream of user events with automatic reconnection"
- }';
- }
-
- rpc UploadUserData {
- option (x_fern_streaming) = '{
- "type": "client_streaming",
- "termination": "client_closes",
- "max_message_size": "10MB"
- }';
- }
-
- rpc ChatWithSupport {
- option (x_fern_streaming) = '{
- "type": "bidirectional_streaming",
- "termination": "either_closes",
- "heartbeat_interval": "30s"
- }';
- }
-}
-```
-
-## Multiple overlays
-
-You can apply multiple overlay files in sequence:
-
-```yaml title="generators.yml" {4-8}
-api:
- specs:
- - spec: proto/user_service.proto
- overlays:
- - base-overlay.yml
- - sdk-overlay.yml
- - docs-overlay.yml
- - examples-overlay.yml
-```
-
-## Environment-specific overlays
-
-Use different overlays for different environments:
-
-```yaml title="generators.yml" {4-7, 12-15}
-groups:
- production:
- audiences: [public]
- specs:
- - spec: proto/user_service.proto
- overlays:
- - production-overlay.yml
- generators:
- - name: fernapi/fern-typescript-node-sdk
- version: 0.8.8
- internal:
- audiences: [admin, internal]
- specs:
- - spec: proto/user_service.proto
- overlays:
- - internal-overlay.yml
- generators:
- - name: fernapi/fern-typescript-node-sdk
- version: 0.8.8
-```
-
-## Field-level overlays
-
-Apply overlays to specific message fields:
-
-```protobuf title="overlay.yml"
-message UserPreferences {
- map notification_settings {
- option (x_fern_parameter_name) = "notifications";
- option (x_fern_field_description) = "User notification preferences with support for email, SMS, and push notifications";
- }
-
- map feature_flags {
- option (x_fern_parameter_name) = "features";
- option (x_fern_field_description) = "Feature flags controlling access to beta and experimental features";
- }
-
- string preferred_language {
- option (x_fern_parameter_name) = "language";
- option (x_fern_validation) = '{
- "enum": ["en", "es", "fr", "de", "zh"],
- "default": "en"
- }';
- }
-}
-```
-
-## Validation overlays
-
-Add validation rules to existing fields:
-
-```protobuf title="overlay.yml"
-message CreateUserRequest {
- string email {
- option (x_fern_validation) = '{
- "format": "email",
- "required": true,
- "description": "Must be a valid email address"
- }';
- }
-
- string name {
- option (x_fern_validation) = '{
- "min_length": 1,
- "max_length": 100,
- "required": true,
- "pattern": "^[a-zA-Z\\s]+$"
- }';
- }
-
- int32 age {
- option (x_fern_validation) = '{
- "minimum": 0,
- "maximum": 120,
- "description": "Age in years"
- }';
- }
-}
-```
-
-Overlays are applied in order, allowing you to build up customizations incrementally while keeping your original Protocol Buffer files clean and focused on the core service definition.
\ No newline at end of file
diff --git a/fern/products/api-def/openapi-pages/extensions/overview.md b/fern/products/api-def/openapi-pages/extensions/overview.md
index fe3030b38..a68db4922 100644
--- a/fern/products/api-def/openapi-pages/extensions/overview.md
+++ b/fern/products/api-def/openapi-pages/extensions/overview.md
@@ -2,7 +2,9 @@
title: Overview of OpenAPI extensions
description: Learn about Fern's OpenAPI extensions
---
-Fern supports a variety of OpenAPI extensions that enhance your API specification and generate higher-quality SDKs. You can apply these extensions in two ways: by overlaying them in separate override files or by embedding them directly in your OpenAPI specification.
+Fern supports a variety of OpenAPI extensions that enhance your API specification and generate higher-quality SDKs.
+
+You can apply these extensions in two ways: by overlaying them in separate override files or by embedding them directly in your OpenAPI specification. See [Overrides](/api-definitions/overview/overrides) for more information.
## Available extensions
@@ -29,8 +31,6 @@ The table below shows all available extensions and links to detailed documentati
If there's an extension you want that doesn't already exist, file an [issue](https://github.com/fern-api/fern/issues/new) to start a discussion about it.
-
-
### FastAPI
FastAPI allows you to add extensions directly in your route decorators and models. See our [FastAPI integration guide](/learn/api-definitions/openapi/frameworks/fastapi) for detailed examples.
diff --git a/fern/products/api-def/openapi-pages/overrides.mdx b/fern/products/api-def/openapi-pages/overrides.mdx
deleted file mode 100644
index 50d6462d7..000000000
--- a/fern/products/api-def/openapi-pages/overrides.mdx
+++ /dev/null
@@ -1,74 +0,0 @@
----
-title: Overlay customizations on an existing OpenAPI spec
-subtitle: Can't directly modify your OpenAPI spec? No worries, use an overrides file instead.
----
-
-If you generate your OpenAPI from server code, you may want to tweak your OpenAPI Spec without having to
-touch the generated file. Fern supports this via an `overrides` file.
-
-
-```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'
-```
-
-
-## Configuration
-
-Follow the steps below to configure your OpenAPI overrides:
-
-
-### Create an `overrides.yml`
-
-Simply create a yaml file and write down all the overrides you want to add:
-
-```yaml overrides.yml
-paths:
- /v1/history:
- get:
- x-fern-sdk-group-name:
- - history
- x-fern-sdk-method-name: get_all
-```
-
-### Reference the file in your `generators.yml`
-
-```yml generators.yml
-api:
- path: ../openapi.yml
- overrides: ../overrides.yml
-```
-
- 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.
-
-
-
diff --git a/fern/products/api-def/openrpc-pages/extensions/overview.md b/fern/products/api-def/openrpc-pages/extensions/overview.md
index b6ed95567..50e6b82ee 100644
--- a/fern/products/api-def/openrpc-pages/extensions/overview.md
+++ b/fern/products/api-def/openrpc-pages/extensions/overview.md
@@ -3,7 +3,9 @@ title: Overview of OpenRPC extensions
description: Learn about Fern's OpenRPC extensions for generating higher-quality SDKs
---
-Fern supports a variety of OpenRPC extensions that enhance your API specification and generate higher-quality SDKs. You can apply these extensions in two ways: by overlaying them in separate override files or by embedding them directly in your OpenRPC specification.
+Fern supports a variety of OpenRPC extensions that enhance your API specification and generate higher-quality SDKs.
+
+You can apply these extensions in two ways: by overlaying them in separate override files or by embedding them directly in your OpenRPC specification. See [Overrides](/api-definitions/overview/overrides) for more information.
## Available extensions
@@ -25,6 +27,4 @@ The table below shows all available extensions and links to detailed documentati
If there's an extension you want that doesn't already exist, file an [issue](https://github.com/fern-api/fern/issues/new) to start a discussion about it.
-
-
-
\ No newline at end of file
+
\ No newline at end of file
diff --git a/fern/products/api-def/openrpc-pages/overrides.mdx b/fern/products/api-def/openrpc-pages/overrides.mdx
deleted file mode 100644
index a3ae23e57..000000000
--- a/fern/products/api-def/openrpc-pages/overrides.mdx
+++ /dev/null
@@ -1,274 +0,0 @@
----
-title: Overlay Customizations
-subtitle: Use overlay files to modify your OpenRPC specification without editing the original
----
-
-Overlays allow you to modify your OpenRPC specification without directly editing the original file. This is useful for:
-- Adding Fern-specific extensions
-- Customizing documentation
-- Adding examples and descriptions
-- Overriding specific properties
-
-## Configure overlays
-
-To use overlays, add them to your `generators.yml` file:
-
-```yaml title="generators.yml" {3-5}
-api:
- specs:
- - spec: openrpc.yml
- overlays:
- - overlay.yml
- generators:
- - name: fernapi/fern-typescript-node-sdk
- version: 0.8.8
-```
-
-## Overlay file structure
-
-Overlay files follow the [OpenAPI Overlay Specification](https://spec.openapis.org/overlay/v1.0.0) format:
-
-```yaml title="overlay.yml"
-overlay: 1.0.0
-info:
- title: OpenRPC Fern Extensions
- version: 1.0.0
-actions:
- - target: $.methods[?(@.name == 'user.create')]
- update:
- x-fern-sdk-method-name: create
- summary: Create a new user account
- - target: $.methods[?(@.name == 'order.list')]
- update:
- description: Retrieve orders with optional filtering and pagination
- x-fern-audiences:
- - public
-```
-
-## Add method names
-
-Override SDK method names for better developer experience:
-
-```yaml title="overlay.yml" {7-9}
-overlay: 1.0.0
-info:
- title: SDK Method Names
- version: 1.0.0
-actions:
- - target: $.methods[?(@.name == 'user.getById')]
- update:
- x-fern-sdk-method-name: getUser
- summary: Retrieve user by ID with enhanced details
- - target: $.methods[?(@.name == 'order.createNew')]
- update:
- x-fern-sdk-method-name: create
- summary: Create order with automatic validation
-```
-
-## Add examples
-
-Enhance your specification with examples:
-
-```yaml title="overlay.yml" {7-20}
-overlay: 1.0.0
-info:
- title: Method Examples
- version: 1.0.0
-actions:
- - target: $.methods[?(@.name == 'user.create')]
- update:
- examples:
- - name: StandardUser
- description: Create a regular user
- params:
- userData:
- email: "john@example.com"
- name: "John Doe"
- role: "user"
- result:
- id: "user_123"
- email: "john@example.com"
- name: "John Doe"
- createdAt: "2024-01-15T10:30:00Z"
-```
-
-## Filter with audiences
-
-Add audience filtering to methods:
-
-```yaml title="overlay.yml" {7-9, 12-14}
-overlay: 1.0.0
-info:
- title: Audience Filtering
- version: 1.0.0
-actions:
- - target: $.methods[?(@.name == 'admin.getUsers')]
- update:
- x-fern-audiences:
- - admin
- - target: $.methods[?(@.name == 'debug.getSystemInfo')]
- update:
- x-fern-audiences:
- - internal
-```
-
-## Add documentation
-
-Enhance descriptions and documentation:
-
-```yaml title="overlay.yml" {7-14}
-overlay: 1.0.0
-info:
- title: Enhanced Documentation
- version: 1.0.0
-actions:
- - target: $.methods[?(@.name == 'payment.process')]
- update:
- description: |
- Process a payment transaction with comprehensive validation and fraud detection.
-
- This method supports multiple payment methods including credit cards,
- digital wallets, and bank transfers. All transactions are processed
- securely with PCI DSS compliance.
-
- Returns a payment result with transaction details or error information.
- summary: Process payment with fraud detection
-```
-
-## Server configurations
-
-Add server-specific configurations:
-
-```yaml title="overlay.yml" {7-12}
-overlay: 1.0.0
-info:
- title: Server Extensions
- version: 1.0.0
-actions:
- - target: $.servers[?(@.name == 'production')]
- update:
- x-fern-server-name: Production
- description: Production environment with high availability and monitoring
- variables:
- region:
- default: us-east-1
- enum: [us-east-1, us-west-2, eu-west-1]
- description: AWS region for the API server
-```
-
-## Add parameter customizations
-
-Customize parameter names and descriptions:
-
-```yaml title="overlay.yml" {7-18}
-overlay: 1.0.0
-info:
- title: Parameter Customizations
- version: 1.0.0
-actions:
- - target: $.methods[?(@.name == 'user.search')].params[?(@.name == 'search_criteria')]
- update:
- x-fern-parameter-name: searchCriteria
- description: |
- Search criteria for finding users. Supports multiple filters:
- - name: Partial name matching (case-insensitive)
- - email: Exact or partial email matching
- - role: Filter by user role
- - status: Filter by account status
- - dateRange: Filter by creation date range
- schema:
- type: object
- properties:
- name:
- type: string
- description: Partial name search (minimum 2 characters)
- email:
- type: string
- description: Email search pattern
- role:
- type: string
- enum: [user, admin, moderator]
- status:
- type: string
- enum: [active, inactive, suspended]
-```
-
-## Add error documentation
-
-Enhance error handling information:
-
-```yaml title="overlay.yml" {7-25}
-overlay: 1.0.0
-info:
- title: Error Documentation
- version: 1.0.0
-actions:
- - target: $.methods[?(@.name == 'order.create')]
- update:
- errors:
- - code: -32001
- message: Insufficient inventory
- data:
- type: object
- properties:
- productId:
- type: string
- availableQuantity:
- type: integer
- requestedQuantity:
- type: integer
- - code: -32002
- message: Payment authorization failed
- data:
- type: object
- properties:
- paymentMethod:
- type: string
- errorCode:
- type: string
- retryAllowed:
- type: boolean
-```
-
-## Multiple overlays
-
-You can apply multiple overlay files in sequence:
-
-```yaml title="generators.yml" {4-8}
-api:
- specs:
- - spec: openrpc.yml
- overlays:
- - base-overlay.yml
- - sdk-overlay.yml
- - docs-overlay.yml
- - examples-overlay.yml
-```
-
-## Environment-specific overlays
-
-Use different overlays for different environments:
-
-```yaml title="generators.yml" {4-7, 12-15}
-groups:
- production:
- audiences: [public]
- specs:
- - spec: openrpc.yml
- overlays:
- - production-overlay.yml
- generators:
- - name: fernapi/fern-typescript-node-sdk
- version: 0.8.8
- internal:
- audiences: [admin, internal]
- specs:
- - spec: openrpc.yml
- overlays:
- - internal-overlay.yml
- generators:
- - name: fernapi/fern-typescript-node-sdk
- version: 0.8.8
-```
-
-Overlays are applied in order, allowing you to build up customizations incrementally while keeping your original OpenRPC specification clean and focused on the core API definition.
\ No newline at end of file
diff --git a/fern/products/api-def/pages/overrides.mdx b/fern/products/api-def/pages/overrides.mdx
new file mode 100644
index 000000000..ce538ccf4
--- /dev/null
+++ b/fern/products/api-def/pages/overrides.mdx
@@ -0,0 +1,175 @@
+---
+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:
+
+* Your API specification is auto-generated from server code
+* You need different configurations for SDKs versus documentation
+
+
+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.
+
+
+## Implement overrides
+
+
+
+
+[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
+```
+
+ 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.
+
+
+
+
+```yml title="overrides.yml" {4-5}
+paths:
+ /users:
+ post:
+ x-fern-sdk-group-name: users
+ x-fern-sdk-method-name: create
+```
+
+
+
+
+```yaml title="generators.yml"
+api:
+ specs:
+ - openapi: spec-file.yml
+ overrides: ./overrides.yml
+```
+
+
+Now when you run `fern generate`, Fern combines your original API specification with the overrides file:
+
+
+```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'
+```
+
+
+
+
+## Separate overrides for SDKs and Docs
+
+For separate SDK and documentation configurations, you can use different override files in separate folders with their own `generators.yml` files.
+
+```bash
+fern/
+ ├─ fern.config.json
+ ├─ generators.yml
+ └─ apis/
+ ├─ docs/ # Documentation configuration
+ │ ├─ generators.yml
+ │ └─ docs-overrides.yml # Documentation-specific overrides
+ ├─ sdks/ # SDK configuration
+ │ ├─ generators.yml
+ │ └─ sdk-overrides.yml # SDK-specific overrides
+ └─ openapi/
+ └─ openapi.yml # Original API specification
+```
+
+Both `generators.yml` files can be identical except for pointing to different override files:
+
+
+
+
+```yaml title="docs/generators.yml"
+api:
+ specs:
+ - openapi: ../openapi/openapi.yml
+ overrides: ./docs-overrides.yml
+```
+
+
+```yaml title="sdks/generators.yml"
+api:
+ specs:
+ - openapi: ../openapi/openapi.yml
+ overrides: ./sdk-overrides.yml
+```
+
+
+
+## Overrides for different environments
+
+You can configure different override files for different environments. Overrides are applied in order, allowing you to build up customizations incrementally while keeping your original specification clean and focused.
+
+```yaml title="generators.yml" {4-7, 12-15}
+groups:
+ production:
+ audiences: [public]
+ specs:
+ - openrpc: openrpc.yml
+ overrides:
+ - production-override.yml
+ generators:
+ - name: fernapi/fern-typescript-node-sdk
+ version: 0.8.8
+ internal:
+ audiences: [admin, internal]
+ specs:
+ - openrpc: openrpc.yml
+ override:
+ - internal-override.yml
+ generators:
+ - name: fernapi/fern-typescript-node-sdk
+ version: 0.8.8
+```
+
+## Definition-specific customizations
+
+Learn more about the customizations you can make for each definition:
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/fern/products/api-def/pages/project-structure.mdx b/fern/products/api-def/pages/project-structure.mdx
index 96fe64d8c..09cfb5ad2 100644
--- a/fern/products/api-def/pages/project-structure.mdx
+++ b/fern/products/api-def/pages/project-structure.mdx
@@ -18,6 +18,10 @@ fern/
└─ spec-file.yml # API definition file
```
+
+ Beyond the core files, you can optionally use an overrides file to customize your API definition without modifying the original spec. See [Overrides](/api-definitions/overview/overrides) for instructions.
+
+
### `fern.config.json file`
Every fern folder has a single `fern.config.json` file. This file stores the organization and
@@ -38,8 +42,9 @@ determinism.
The `generators.yml` file includes information about where your API definition file is located. It also [configures the SDKs](/sdks/overview/github) you're generating for your API.
```yaml title="generators.yml"
-api:
- path: ./path/to/openapi.yml
+api:
+ specs:
+ - openapi: spec-file.yml
```
### API definition file
@@ -48,6 +53,12 @@ api:
For the other specification formats ([OpenAPI](/api-definitions/openapi/overview), [AsyncAPI](/api-definitions/asyncapi/overview), [OpenRPC](/api-definitions/openrpc/overview), and [gRPC](/api-definitions/grpc/overview)), you'll have a single self-contained specification file.
+
## Multiple API definitions
+
+### Docs configuration
+
+APIs in docs are specified by [setting the `api-name` property](/docs/api-references/generate-api-ref#include-more-than-one-api-reference).
+
diff --git a/fern/products/docs/pages/api-references/generate-api-ref.mdx b/fern/products/docs/pages/api-references/generate-api-ref.mdx
index d0d1b9958..b14c1caa6 100644
--- a/fern/products/docs/pages/api-references/generate-api-ref.mdx
+++ b/fern/products/docs/pages/api-references/generate-api-ref.mdx
@@ -35,14 +35,50 @@ navigation:
More on customizing your API Reference [here](/learn/docs/api-references/customize-api-reference-layout).
### Include more than one API Reference
+
To include multiple, distinct API definitions in your documentation, you can indicate which to include using the `api-name` property. The `api-name` corresponds to the name of the folder where your API definition is housed.
+For example, your file structure might look like this:
+
+```bash
+fern/
+ ├─ fern.config.json
+ ├─ docs.yml
+ ├─ plant-api/
+ │ └─ api.yml # API definition
+ └─ garden-api/
+ └─ api.yml # API definition
+```
+
+For a simple setup without tabs, you can include multiple API references directly in your navigation:
+
```yaml title="docs.yml"
navigation:
- api: Plant Store
- api-name: plant-api
+ api-name: plant-api # Matches folder name containing your API definition
- api: Garden
- api-name: garden-api
+ api-name: garden-api # Matches folder name containing your API definition
```
+When using tabs, each API reference must be placed within a tab's `layout`:
+```yaml title="docs.yml" {12, 17}
+tabs:
+ plant-api:
+ display-name: Plant Store API
+ icon: leaf
+ garden-api:
+ display-name: Garden API
+ icon: tree
+navigation:
+ - tab: plant-api # References the tab defined above
+ layout:
+ - api: Plant Store API
+ api-name: plant-api # Matches folder name containing your API definition
+ skip-slug: true
+ - tab: garden-api # References the tab defined above
+ layout:
+ - api: Garden API
+ api-name: garden-api # Matches folder name containing your API definition
+ skip-slug: true
+```
diff --git a/fern/products/docs/pages/getting-started/project-structure.mdx b/fern/products/docs/pages/getting-started/project-structure.mdx
index c8873cde8..d4ca8d041 100644
--- a/fern/products/docs/pages/getting-started/project-structure.mdx
+++ b/fern/products/docs/pages/getting-started/project-structure.mdx
@@ -111,10 +111,14 @@ title: Fern's Documentation
The `openapi` folder contains the OpenAPI Specification file for your API Reference section. Fern will read either a YAML or JSON file from this folder to generate the API Reference documentation. If you don't have an API Reference section, you can skip this folder.
+
+ In addition to your specification file, you can optionally [add an overrides file](/api-definitions/overview/overrides) for additional customizations.
+
```bash
openapi
- └─ openapi.yaml # OR openapi.json
+ ├─ openapi.yaml # OR openapi.json
+ └─ overrides.yaml
```
@@ -123,12 +127,16 @@ title: Fern's Documentation
The `definition` folder contains the Fern Definition YAML files used to generate the API Reference section. If you don't have an API Reference section, you can skip this folder.
+
+ In addition to your specification file, you can optionally [add an overrides file](/api-definitions/overview/overrides) for additional customizations.
+
```bash
definition
├─ pets.yaml
├─ owners.yaml
├─ stores.yaml
+ ├─ overrides.yaml
└─ api.yaml
```
@@ -137,14 +145,18 @@ title: Fern's Documentation
- If you have multiple APIs, you can organize them into separate folders within the `apis` folder. Each API should have its own API definition. For example:
+ If you have multiple APIs, you can organize them into separate folders within the `apis` folder. Each API should have its own API definition and [(optional) overrides file](/api-definitions/overview/overrides).
+
+ For example:
```bash
apis
├─ admin
- │ └─ openapi.json
+ │ ├─ openapi.json
+ │ └─ overrides.yaml
├─ user
- │ └─ openapi.yaml
+ │ ├─ openapi.yaml
+ │ └─ overrides.yaml
```
diff --git a/fern/products/sdks/github-setup.mdx b/fern/products/sdks/github-setup.mdx
index 1126259a4..93f7dd581 100644
--- a/fern/products/sdks/github-setup.mdx
+++ b/fern/products/sdks/github-setup.mdx
@@ -17,7 +17,8 @@ Fern recommends a parent-child repository structure containing:
│ └─ fern/
│ ├─ fern.config.json # Root-level config
│ ├─ generators.yml # References child repos
-│ └─ definition/ # or openapi/, asyncapi/, etc.
+│ └─ definition/
+ ├─ overrides.yml # Optional overrides file
│ └─ api.yml # Your API definition
├─ typescript-sdk-repo # Child repository
├─ python-sdk-repo # Child repository
@@ -78,6 +79,10 @@ See the [`generators.yml` reference page](/sdks/reference/generators-yml) for co
For information on how to structure your API definition files, see [Project structure (API Definitions)](/api-definitions/overview/project-structure).
+### Optional: `overrides.yml` file
+
+You can optionally add an `overrides.yml` file to customize your API definition without modifying the original spec file. For more information, see [Overrides](/api-definitions/overview/overrides).
+
## Child repository structure
Each SDK has its own repository with the following structure:
diff --git a/fern/snippets/multiple-apis.mdx b/fern/snippets/multiple-apis.mdx
index 2bbe1b952..5beb50ac0 100644
--- a/fern/snippets/multiple-apis.mdx
+++ b/fern/snippets/multiple-apis.mdx
@@ -15,4 +15,12 @@ fern/
├─ generators.yml # Required: points to API spec
└─ openapi/
├─ openapi.yml # API Definition file
-```
\ No newline at end of file
+```
+
+### SDK generation
+
+To [specify the API for SDK generation](/cli-api-reference/cli-reference/commands#api) use the `--api` flag:
+
+```bash
+fern generate --api public-api
+```
\ No newline at end of file
diff --git a/fern/snippets/overlay-embed-extensions.mdx b/fern/snippets/overlay-embed-extensions.mdx
deleted file mode 100644
index 5021439ca..000000000
--- a/fern/snippets/overlay-embed-extensions.mdx
+++ /dev/null
@@ -1,66 +0,0 @@
-## Overlaying extensions
-
-Overlaying extensions allows you to keep your original API specification clean while adding Fern-specific customizations in a separate file. This approach is ideal when you're using multiple tools that consume your API spec, or when you want to maintain a pristine source specification.
-
-To use overlays, specify an overrides file in your `generators.yml` configuration.
-
-The example below shows how to overlay SDK naming extensions. The first tab shows the `generators.yml` configuration that references an overrides file, the second tab contains the overrides file with Fern extensions, and the third tab shows the final result when the extensions are applied to your original API specification.
-
-
- ```yaml title="generators.yml" {3}
- api:
- path: ./spec-folder/spec-file.yaml
- overrides: ./spec-folder/overrides.yaml # Reference your overrides file
- default-group: sdk
- groups:
- sdk:
- generators:
- - name: fernapi/fern-python-sdk
- version: 2.2.0
- ```
-
- ```yaml title="overrides.yml" {4-5}
- paths:
- /users:
- get:
- x-fern-sdk-group-name: users
- x-fern-sdk-method-name: get
- ```
-
- ```yaml title="Overlaid spec" {4-5}
- paths:
- /users:
- get:
- x-fern-sdk-group-name: users
- x-fern-sdk-method-name: get
- summary: Get a list of users
- description: Retrieve a list of users from the system.
- responses:
- '200':
- description: Successful response
- '500':
- description: Internal Server Error
- ```
-
-
-
-## Embedding extensions
-
-Instead of using overlay files, you can embed Fern extensions directly within your API specification or source code. This approach is useful when you want to keep extensions close to your API definitions or when using frameworks that support custom extensions.
-
-### Direct embedding
-
-You can add Fern extensions directly to your API specification:
-
-```yaml title="spec-file.yml" {4-6}
-paths:
- /users:
- get:
- x-fern-sdk-group-name: users
- x-fern-sdk-method-name: listUsers
- x-fern-availability: generally-available
- summary: Get a list of users
- responses:
- '200':
- description: Successful response
-```
\ No newline at end of file