diff --git a/fern/apis/generators-yml/definition/generators.yml b/fern/apis/generators-yml/definition/generators.yml index 86ed229f8..0d0efaece 100644 --- a/fern/apis/generators-yml/definition/generators.yml +++ b/fern/apis/generators-yml/definition/generators.yml @@ -167,6 +167,13 @@ types: - v1 - v2 + OverridesSchema: + discriminated: false + docs: Paths to the overrides configuration. Can be a single path or an array of paths applied sequentially. + union: + - string + - list + APIDefinitionWithOverridesSchema: properties: path: APIDefinitionPathSchema @@ -174,8 +181,8 @@ types: type: optional docs: The URL of the API definition origin, from which the file should be polled. overrides: - type: optional - docs: Path to the OpenAPI or AsyncAPI overrides + type: optional + docs: Paths to the overrides configuration. Can be a single path or an array of paths applied sequentially. audiences: type: optional> docs: Audiences that you would like to filter to @@ -190,8 +197,8 @@ types: type: string docs: The path to the `.proto` directory root (e.g. `proto`). overrides: - type: optional - docs: Path to the overrides configuration + type: optional + docs: Paths to the overrides configuration. Can be a single path or an array of paths applied sequentially. local-generation: type: optional docs: Whether to compile the `.proto` files locally. By default, we generate remotely. @@ -324,14 +331,14 @@ types: properties: openapi: string origin: optional - overrides: optional + overrides: optional namespace: optional settings: optional OpenRPCSpecSchema: properties: openrpc: string - overrides: optional + overrides: optional namespace: optional AsyncAPISettingsSchema: @@ -346,7 +353,7 @@ types: properties: asyncapi: string origin: optional - overrides: optional + overrides: optional namespace: optional settings: optional @@ -367,4 +374,4 @@ types: ProtobufSpecSchema: properties: - proto: ProtobufDefinitionSchema \ No newline at end of file + proto: ProtobufDefinitionSchema diff --git a/fern/products/api-def/pages/overrides.mdx b/fern/products/api-def/pages/overrides.mdx index c0d633273..e79558aa5 100644 --- a/fern/products/api-def/pages/overrides.mdx +++ b/fern/products/api-def/pages/overrides.mdx @@ -58,6 +58,17 @@ api: - openapi: spec-file.yml overrides: ./overrides.yml ``` + +You can also specify multiple override files. When multiple paths are provided, overrides are applied sequentially in the order listed: + +```yaml title="generators.yml" +api: + specs: + - openapi: spec-file.yml + overrides: + - ./base-overrides.yml + - ./sdk-overrides.yml +``` Now when you run `fern generate`, Fern combines your original API specification with the overrides file: @@ -100,6 +111,25 @@ paths: +## Multiple override files + +The `overrides` field accepts a single path or a list of paths. When multiple paths are provided, overrides are applied sequentially in order, with later files taking precedence over earlier ones for conflicting keys. This is useful for: + +* Separating vendor-specific SDK customizations from shared API overrides +* Layering team-specific overrides on top of base configurations +* Keeping override files small and focused on specific concerns + +```yaml title="generators.yml" +api: + specs: + - openapi: openapi.yml + overrides: + - ./base-overrides.yml # Shared overrides (e.g., SDK method names) + - ./team-overrides.yml # Team-specific customizations +``` + +Multiple override files are supported for all spec types: OpenAPI, AsyncAPI, OpenRPC, and Protobuf. + ## Separate overrides for SDKs and docs diff --git a/fern/products/sdks/reference/generators-yml-reference.mdx b/fern/products/sdks/reference/generators-yml-reference.mdx index 87e6c0bd2..8b77484fc 100644 --- a/fern/products/sdks/reference/generators-yml-reference.mdx +++ b/fern/products/sdks/reference/generators-yml-reference.mdx @@ -221,7 +221,7 @@ api: specs: - asyncapi: "./asyncapi.yml" origin: "https://api.example.com/asyncapi.json" - overrides: "./asyncapi-overrides.yml" + overrides: "./asyncapi-overrides.yml" # or a list of paths namespace: "events" settings: message-naming: "v2" @@ -237,8 +237,18 @@ api: URL of the API definition origin for pulling updates. - - Path to AsyncAPI overrides file. + + Path to an AsyncAPI [overrides](/learn/api-definitions/overview/overrides) file, or a list of paths to multiple override files applied sequentially. + + ```yaml + # Single override file + overrides: ./asyncapi-overrides.yml + + # Multiple override files (applied in order) + overrides: + - ./base-overrides.yml + - ./sdk-overrides.yml + ``` @@ -287,8 +297,18 @@ api: Path to the OpenRPC specification file. - - Path to OpenRPC overrides file. + + Path to an OpenRPC [overrides](/learn/api-definitions/overview/overrides) file, or a list of paths to multiple override files applied sequentially. + + ```yaml + # Single override file + overrides: ./overrides.yml + + # Multiple override files (applied in order) + overrides: + - ./base-overrides.yml + - ./sdk-overrides.yml + ``` diff --git a/fern/snippets/grpc-specs.mdx b/fern/snippets/grpc-specs.mdx index c7261660d..27246a449 100644 --- a/fern/snippets/grpc-specs.mdx +++ b/fern/snippets/grpc-specs.mdx @@ -15,8 +15,18 @@ api: Path to the target `.proto` file (e.g., `proto/user/v1/user.proto`). Omit to generate docs for the entire root folder. - - Path to the overrides configuration file. Used for SDK generation only, not for documentation generation. + + Path to the overrides configuration file, or a list of paths to multiple override files applied sequentially. Used for SDK generation only, not for documentation generation. + + ```yaml + # Single override file + overrides: ./overrides.yml + + # Multiple override files (applied in order) + overrides: + - ./base-overrides.yml + - ./sdk-overrides.yml + ``` diff --git a/fern/snippets/openapi-specs.mdx b/fern/snippets/openapi-specs.mdx index caf37f700..3003cacd5 100644 --- a/fern/snippets/openapi-specs.mdx +++ b/fern/snippets/openapi-specs.mdx @@ -4,7 +4,7 @@ api: - openapi: "./openapi.yml" origin: "https://api.example.com/openapi.json" overlays: "./openapi-overlays.yml" - overrides: "./openapi-overrides.yml" + overrides: "./openapi-overrides.yml" # or a list of paths namespace: "v1" settings: title-as-schema-name: true @@ -30,8 +30,18 @@ api: Path to an [OpenAPI Overlay](/learn/api-definitions/openapi/overlays) file. Overlays follow the [OpenAPI Overlay Specification](https://spec.openapis.org/overlay/v1.0.0.html) and are the recommended approach for customizing OpenAPI specifications. - - Path to OpenAPI overrides file. Consider using `overlays` instead for a standards-based approach. + + Path to an OpenAPI [overrides](/learn/api-definitions/overview/overrides) file, or a list of paths to multiple override files applied sequentially. Consider using `overlays` instead for a standards-based approach. + + ```yaml + # Single override file + overrides: ./overrides.yml + + # Multiple override files (applied in order) + overrides: + - ./base-overrides.yml + - ./sdk-overrides.yml + ```