From c72ffc89b62ef48803bb826a5a95263457e64a7b Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Thu, 27 Aug 2026 17:06:19 +0000 Subject: [PATCH 1/3] docs: compiling GraphQL SDL split across multiple files Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- .../api-references/generate-graphql-ref.mdx | 32 +++++++++++++++++-- .../docs/pages/changelog/2026-08-27.mdx | 7 ++++ 2 files changed, 37 insertions(+), 2 deletions(-) create mode 100644 fern/products/docs/pages/changelog/2026-08-27.mdx diff --git a/fern/products/docs/pages/api-references/generate-graphql-ref.mdx b/fern/products/docs/pages/api-references/generate-graphql-ref.mdx index ae5fb5a17a..d0a489787f 100644 --- a/fern/products/docs/pages/api-references/generate-graphql-ref.mdx +++ b/fern/products/docs/pages/api-references/generate-graphql-ref.mdx @@ -73,14 +73,42 @@ navigation: api-name: garden-graphql ``` +### Compile a schema split across multiple files + +A schema split across several SDL files, the typical shape for [Apollo Federation](https://www.apollographql.com/docs/federation/) subgraphs, compiles into a single schema. List each file as its own spec and give the specs the same `name`: + +```yaml generators.yml +api: + specs: + - graphql: plants.graphql + name: Plants + - graphql: gardens.graphql + name: Plants +``` + +Specs that share a `name` are parsed together and merged, so a file can reference types defined in a sibling file and each file can `extend type Query` or `extend type Mutation`. Specs with different `name` values, and specs in different API workspaces, remain independent. Specs listed without a `name` share one namespace and merge. + +The merged schema matches the client-facing schema Apollo derives from a supergraph: + +- Federation directives such as `@link`, `@key`, `@external`, `@shareable`, and `@tag`, along with their definitions, are stripped. Runtime composition semantics such as `@requires` and `@provides` are not modeled, since merging serves documentation rather than execution. +- `@inaccessible` types and members are omitted from the reference, as is anything that referenced them. +- `extend type X` is folded into the type definition, members are merged by name, and schema root operation types are merged. +- `@deprecated` operations, arguments, fields, and enum values are marked as deprecated, with the deprecation reason appended to the description. + +Conflicts do not fail the build. When two files declare the same member or directive definition with differing shapes, the first declaration wins and Fern logs a warning naming both files. Declaring an identical key field in two subgraphs is not a conflict. + + + A workspace with several GraphQL specs in one namespace previously resolved colliding types and operations last-wins, without a warning. Those specs now merge first-wins. To keep the previous output, reorder the specs or give them distinct `name` values. + + ### Configuration properties - Path to your GraphQL schema file. You can include multiple GraphQL specs if your project exposes more than one GraphQL API. + Path to your GraphQL schema file. Include multiple GraphQL specs if your project exposes more than one GraphQL API, or if one schema is split across files. - Name of the folder that operations from this spec appear under in the API Reference sidebar. Use this to group related GraphQL operations together. + Name of the folder that operations from this spec appear under in the API Reference sidebar. Use this to group related GraphQL operations together. Specs that share a `name` are compiled into one schema. diff --git a/fern/products/docs/pages/changelog/2026-08-27.mdx b/fern/products/docs/pages/changelog/2026-08-27.mdx new file mode 100644 index 0000000000..f35107ef39 --- /dev/null +++ b/fern/products/docs/pages/changelog/2026-08-27.mdx @@ -0,0 +1,7 @@ +## GraphQL schemas split across multiple files + +api-reference, generators.yml + +You can now generate a single GraphQL API Reference from a schema split across several SDL files, including Apollo Federation subgraphs. List each file as its own spec in `generators.yml` and give the specs the same `name`, and Fern compiles them into one schema: federation directives are stripped, `@inaccessible` members are omitted, and `@deprecated` members are marked as deprecated in the reference. + + From b5cbb839830fa721a247f987f1ced2a695a023d1 Mon Sep 17 00:00:00 2001 From: "devin.logan" Date: Mon, 31 Aug 2026 15:12:17 +0000 Subject: [PATCH 2/3] docs(graphql): condense multi-file SDL section Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- .../pages/api-references/generate-graphql-ref.mdx | 13 +++---------- fern/products/docs/pages/changelog/2026-08-27.mdx | 2 +- 2 files changed, 4 insertions(+), 11 deletions(-) diff --git a/fern/products/docs/pages/api-references/generate-graphql-ref.mdx b/fern/products/docs/pages/api-references/generate-graphql-ref.mdx index d0a489787f..8a849f31a3 100644 --- a/fern/products/docs/pages/api-references/generate-graphql-ref.mdx +++ b/fern/products/docs/pages/api-references/generate-graphql-ref.mdx @@ -86,19 +86,12 @@ api: name: Plants ``` -Specs that share a `name` are parsed together and merged, so a file can reference types defined in a sibling file and each file can `extend type Query` or `extend type Mutation`. Specs with different `name` values, and specs in different API workspaces, remain independent. Specs listed without a `name` share one namespace and merge. +Specs that share a `name`, or that omit `name`, are parsed together, so a file can reference types defined in a sibling file and each file can `extend type Query` or `extend type Mutation`. Specs with different `name` values, and specs in different API workspaces, remain independent. -The merged schema matches the client-facing schema Apollo derives from a supergraph: - -- Federation directives such as `@link`, `@key`, `@external`, `@shareable`, and `@tag`, along with their definitions, are stripped. Runtime composition semantics such as `@requires` and `@provides` are not modeled, since merging serves documentation rather than execution. -- `@inaccessible` types and members are omitted from the reference, as is anything that referenced them. -- `extend type X` is folded into the type definition, members are merged by name, and schema root operation types are merged. -- `@deprecated` operations, arguments, fields, and enum values are marked as deprecated, with the deprecation reason appended to the description. - -Conflicts do not fail the build. When two files declare the same member or directive definition with differing shapes, the first declaration wins and Fern logs a warning naming both files. Declaring an identical key field in two subgraphs is not a conflict. +The merged schema matches the client-facing schema Apollo derives from a supergraph: federation directives such as `@link`, `@key`, and `@external` are stripped, `@inaccessible` types and members are omitted, `extend type X` is folded into its type definition, and `@deprecated` members are marked as deprecated with the reason appended to the description. When two files declare the same member with differing shapes, the first declaration wins and Fern logs a warning naming both files. - A workspace with several GraphQL specs in one namespace previously resolved colliding types and operations last-wins, without a warning. Those specs now merge first-wins. To keep the previous output, reorder the specs or give them distinct `name` values. + Specs sharing a namespace previously resolved collisions last-wins, without a warning. To keep the previous output, reorder the specs or give them distinct `name` values. ### Configuration properties diff --git a/fern/products/docs/pages/changelog/2026-08-27.mdx b/fern/products/docs/pages/changelog/2026-08-27.mdx index 6fac9919c9..28a80cdbc1 100644 --- a/fern/products/docs/pages/changelog/2026-08-27.mdx +++ b/fern/products/docs/pages/changelog/2026-08-27.mdx @@ -2,7 +2,7 @@ api-reference, generators.yml -You can now generate a single GraphQL API Reference from a schema split across several SDL files, including Apollo Federation subgraphs. List each file as its own spec in `generators.yml` and give the specs the same `name`, and Fern compiles them into one schema: federation directives are stripped, `@inaccessible` members are omitted, and `@deprecated` members are marked as deprecated in the reference. +You can now generate a single GraphQL API Reference from a schema split across several SDL files, including Apollo Federation subgraphs. List each file as its own spec in `generators.yml` with the same `name`, and Fern compiles them into one schema. From 8378c09b06ba696d524a0707caf16e1ed797c5f2 Mon Sep 17 00:00:00 2001 From: "devin.logan" Date: Mon, 31 Aug 2026 15:16:12 +0000 Subject: [PATCH 3/3] docs(graphql): trim merge-behavior paragraph Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- .../products/docs/pages/api-references/generate-graphql-ref.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fern/products/docs/pages/api-references/generate-graphql-ref.mdx b/fern/products/docs/pages/api-references/generate-graphql-ref.mdx index 8a849f31a3..1c1fa533fa 100644 --- a/fern/products/docs/pages/api-references/generate-graphql-ref.mdx +++ b/fern/products/docs/pages/api-references/generate-graphql-ref.mdx @@ -88,7 +88,7 @@ api: Specs that share a `name`, or that omit `name`, are parsed together, so a file can reference types defined in a sibling file and each file can `extend type Query` or `extend type Mutation`. Specs with different `name` values, and specs in different API workspaces, remain independent. -The merged schema matches the client-facing schema Apollo derives from a supergraph: federation directives such as `@link`, `@key`, and `@external` are stripped, `@inaccessible` types and members are omitted, `extend type X` is folded into its type definition, and `@deprecated` members are marked as deprecated with the reason appended to the description. When two files declare the same member with differing shapes, the first declaration wins and Fern logs a warning naming both files. +The reference shows the client-facing schema: federation directives are stripped and `@inaccessible` types and members are omitted. If two files declare the same member differently, the first declaration wins and Fern logs a warning. Specs sharing a namespace previously resolved collisions last-wins, without a warning. To keep the previous output, reorder the specs or give them distinct `name` values.