From e7eee0ff6d1d3f44a24846e22b7cc89ba30922b7 Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Fri, 22 May 2026 18:35:09 +0000 Subject: [PATCH 1/5] feat: add GraphQL API Reference example Co-Authored-By: Devin Logan --- README.md | 1 + graphql/fern/docs.yml | 45 ++++++++++ graphql/fern/fern.config.json | 4 + graphql/fern/generators.yml | 6 ++ graphql/fern/schema.graphql | 155 ++++++++++++++++++++++++++++++++++ 5 files changed, 211 insertions(+) create mode 100644 graphql/fern/docs.yml create mode 100644 graphql/fern/fern.config.json create mode 100644 graphql/fern/generators.yml create mode 100644 graphql/fern/schema.graphql diff --git a/README.md b/README.md index 485fef1..2cbb183 100644 --- a/README.md +++ b/README.md @@ -9,6 +9,7 @@ Example Fern docs projects. Each top-level folder is a self-contained example wi | Example | Description | Live demo | | --- | --- | --- | | [`docs-starter`](./docs-starter) | Minimal starter project | [docs-starter.docs.buildwithfern.com](https://docs-starter.docs.buildwithfern.com) | +| [`graphql`](./graphql) | GraphQL API Reference from a `.graphql` schema | [graphql.docs.buildwithfern.com](https://graphql.docs.buildwithfern.com) | | [`i18n`](./i18n) | Multi-language docs with English + Japanese translations | [i18n.docs.buildwithfern.com](https://i18n.docs.buildwithfern.com) | | [`multi-source`](./multi-source) | Multi-source docs — six independent projects publishing to one domain with global theme, nested sub-paths, and shared branding | [multi-source.docs.buildwithfern.com](https://multi-source.docs.buildwithfern.com) | | [`versioning`](./docs-versioned) | Versioned site with a version dropdown and a shared page | [versioning.docs.buildwithfern.com](https://versioning.docs.buildwithfern.com) | diff --git a/graphql/fern/docs.yml b/graphql/fern/docs.yml new file mode 100644 index 0000000..08e9f0c --- /dev/null +++ b/graphql/fern/docs.yml @@ -0,0 +1,45 @@ +# yaml-language-server: $schema=https://schema.buildwithfern.dev/docs-yml.json + +instances: + - url: graphql.docs.buildwithfern.com + +title: Plant Store GraphQL API + +layout: + searchbar-placement: header + page-width: full + +navigation: + - api: Plant Store GraphQL API + layout: + - section: Plants + contents: + - operation: QUERY plant + - operation: QUERY plants + - operation: MUTATION createPlant + - operation: MUTATION deletePlant + - section: Orders + contents: + - operation: QUERY order + - operation: QUERY orders + - operation: MUTATION placeOrder + - operation: MUTATION updateOrderStatus + - section: Subscriptions + contents: + - operation: SUBSCRIPTION orderPlaced + - operation: SUBSCRIPTION orderStatusChanged + +colors: + accent-primary: + dark: "#70E155" + light: "#008700" + background: + dark: "#111113" + light: "#FFFFFF" + +navbar-links: + - type: minimal + text: View source + url: https://github.com/fern-api/docs-examples/tree/main/graphql + - type: github + value: https://github.com/fern-api/fern diff --git a/graphql/fern/fern.config.json b/graphql/fern/fern.config.json new file mode 100644 index 0000000..9f41ff5 --- /dev/null +++ b/graphql/fern/fern.config.json @@ -0,0 +1,4 @@ +{ + "organization": "fern-docs-examples", + "version": "5.35.0" +} diff --git a/graphql/fern/generators.yml b/graphql/fern/generators.yml new file mode 100644 index 0000000..b806cd7 --- /dev/null +++ b/graphql/fern/generators.yml @@ -0,0 +1,6 @@ +# yaml-language-server: $schema=https://schema.buildwithfern.dev/generators-yml.json +api: + specs: + - graphql: schema.graphql + name: Plant Store + origin: https://api.example.com/plants/graphql diff --git a/graphql/fern/schema.graphql b/graphql/fern/schema.graphql new file mode 100644 index 0000000..b884b99 --- /dev/null +++ b/graphql/fern/schema.graphql @@ -0,0 +1,155 @@ +""" +A date-time string in ISO 8601 format. +""" +scalar DateTime + +""" +A plant in the catalog. +""" +type Plant { + "Unique identifier for the plant." + id: ID! + "Common name of the plant." + name: String! + "Botanical (Latin) name." + species: String! + "Care difficulty rating." + difficulty: Difficulty! + "Whether the plant is currently in stock." + inStock: Boolean! + "Price in USD cents." + priceInCents: Int! + "Tags describing the plant." + tags: [String!] + "When the plant was added to the catalog." + createdAt: DateTime! +} + +""" +A customer order. +""" +type Order { + "Unique identifier for the order." + id: ID! + "Plants included in the order." + items: [OrderItem!]! + "Current status of the order." + status: OrderStatus! + "When the order was placed." + placedAt: DateTime! +} + +""" +A single line item in an order. +""" +type OrderItem { + "The plant being ordered." + plant: Plant! + "Number of units." + quantity: Int! +} + +""" +Care difficulty levels. +""" +enum Difficulty { + "Minimal care required." + EASY + "Some gardening experience helpful." + MODERATE + "Requires specific conditions and attention." + HARD +} + +""" +Order lifecycle statuses. +""" +enum OrderStatus { + PENDING + CONFIRMED + SHIPPED + DELIVERED + CANCELLED +} + +""" +Input for adding a new plant to the catalog. +""" +input CreatePlantInput { + "Common name of the plant." + name: String! + "Botanical (Latin) name." + species: String! + "Care difficulty rating." + difficulty: Difficulty! + "Price in USD cents." + priceInCents: Int! + "Tags describing the plant." + tags: [String!] +} + +""" +Input for placing a new order. +""" +input PlaceOrderInput { + "Items to include in the order." + items: [OrderItemInput!]! +} + +""" +A single item in a new order. +""" +input OrderItemInput { + "ID of the plant to order." + plantId: ID! + "Number of units." + quantity: Int! +} + +""" +Filter options for listing plants. +""" +input PlantFilter { + "Filter by difficulty level." + difficulty: Difficulty + "Only show plants that are in stock." + inStock: Boolean + "Filter by tag." + tag: String +} + +type Query { + "Look up a plant by its ID." + plant(id: ID!): Plant + + "List plants with optional filtering." + plants(filter: PlantFilter, limit: Int = 20, offset: Int = 0): [Plant!]! + + "Look up an order by its ID." + order(id: ID!): Order + + "List orders, optionally filtered by status." + orders(status: OrderStatus, limit: Int = 20): [Order!]! +} + +type Mutation { + "Add a new plant to the catalog." + createPlant(input: CreatePlantInput!): Plant! + + "Remove a plant from the catalog." + deletePlant(id: ID!): Boolean! + + "Place a new order." + placeOrder(input: PlaceOrderInput!): Order! + + "Update an order's status." + updateOrderStatus(id: ID!, status: OrderStatus!): Order +} + +type Subscription { + "Subscribe to new orders." + orderPlaced: Order! + + "Subscribe to status changes for a specific order." + orderStatusChanged(orderId: ID!): Order! +} From a23c3a69cd4609d28a1aba4e985b645e15d64881 Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Fri, 22 May 2026 18:48:19 +0000 Subject: [PATCH 2/5] feat: add welcome page, assets, and theme to match other examples Co-Authored-By: Devin Logan --- graphql/fern/docs.yml | 64 ++++++---- graphql/fern/docs/assets/favicon.svg | 8 ++ .../fern/docs/assets/fern-logo-primary.svg | 4 + graphql/fern/docs/assets/fern-logo-white.svg | 4 + graphql/fern/docs/assets/logo-dark.svg | 9 ++ graphql/fern/docs/assets/logo-light.svg | 14 +++ graphql/fern/docs/assets/logo.svg | 11 ++ graphql/fern/docs/pages/welcome.mdx | 110 ++++++++++++++++++ graphql/fern/styles.css | 10 ++ 9 files changed, 211 insertions(+), 23 deletions(-) create mode 100644 graphql/fern/docs/assets/favicon.svg create mode 100644 graphql/fern/docs/assets/fern-logo-primary.svg create mode 100644 graphql/fern/docs/assets/fern-logo-white.svg create mode 100644 graphql/fern/docs/assets/logo-dark.svg create mode 100644 graphql/fern/docs/assets/logo-light.svg create mode 100644 graphql/fern/docs/assets/logo.svg create mode 100644 graphql/fern/docs/pages/welcome.mdx create mode 100644 graphql/fern/styles.css diff --git a/graphql/fern/docs.yml b/graphql/fern/docs.yml index 08e9f0c..c7c8381 100644 --- a/graphql/fern/docs.yml +++ b/graphql/fern/docs.yml @@ -3,31 +3,42 @@ instances: - url: graphql.docs.buildwithfern.com -title: Plant Store GraphQL API +title: GraphQL Docs Example layout: searchbar-placement: header page-width: full + tabs-placement: header + +tabs: + home: + display-name: Docs + icon: home + API Reference: + display-name: API Reference + icon: puzzle navigation: - - api: Plant Store GraphQL API + - tab: home layout: - - section: Plants - contents: - - operation: QUERY plant - - operation: QUERY plants - - operation: MUTATION createPlant - - operation: MUTATION deletePlant - - section: Orders + - section: Get started contents: - - operation: QUERY order - - operation: QUERY orders - - operation: MUTATION placeOrder - - operation: MUTATION updateOrderStatus - - section: Subscriptions - contents: - - operation: SUBSCRIPTION orderPlaced - - operation: SUBSCRIPTION orderStatusChanged + - page: Welcome + path: docs/pages/welcome.mdx + icon: fa-duotone fa-house + - tab: API Reference + layout: + - api: Plant Store GraphQL API + +navbar-links: + - type: minimal + text: Fork this repo + url: https://github.com/fern-api/docs-examples + - type: filled + text: Dashboard + url: https://dashboard.buildwithfern.com + - type: github + value: https://github.com/fern-api/fern colors: accent-primary: @@ -37,9 +48,16 @@ colors: dark: "#111113" light: "#FFFFFF" -navbar-links: - - type: minimal - text: View source - url: https://github.com/fern-api/docs-examples/tree/main/graphql - - type: github - value: https://github.com/fern-api/fern +theme: + page-actions: toolbar + footer-nav: minimal + +logo: + dark: docs/assets/logo-dark.svg + light: docs/assets/logo.svg + height: 20 + href: https://buildwithfern.com + +favicon: docs/assets/favicon.svg + +css: styles.css diff --git a/graphql/fern/docs/assets/favicon.svg b/graphql/fern/docs/assets/favicon.svg new file mode 100644 index 0000000..568bb7e --- /dev/null +++ b/graphql/fern/docs/assets/favicon.svg @@ -0,0 +1,8 @@ + + + + \ No newline at end of file diff --git a/graphql/fern/docs/assets/fern-logo-primary.svg b/graphql/fern/docs/assets/fern-logo-primary.svg new file mode 100644 index 0000000..a21927d --- /dev/null +++ b/graphql/fern/docs/assets/fern-logo-primary.svg @@ -0,0 +1,4 @@ + + + + diff --git a/graphql/fern/docs/assets/fern-logo-white.svg b/graphql/fern/docs/assets/fern-logo-white.svg new file mode 100644 index 0000000..9dd77b1 --- /dev/null +++ b/graphql/fern/docs/assets/fern-logo-white.svg @@ -0,0 +1,4 @@ + + + + diff --git a/graphql/fern/docs/assets/logo-dark.svg b/graphql/fern/docs/assets/logo-dark.svg new file mode 100644 index 0000000..144e0e3 --- /dev/null +++ b/graphql/fern/docs/assets/logo-dark.svg @@ -0,0 +1,9 @@ + + + + + + + + + diff --git a/graphql/fern/docs/assets/logo-light.svg b/graphql/fern/docs/assets/logo-light.svg new file mode 100644 index 0000000..7cf2ee2 --- /dev/null +++ b/graphql/fern/docs/assets/logo-light.svg @@ -0,0 +1,14 @@ + + + + + + + + + + + + + + diff --git a/graphql/fern/docs/assets/logo.svg b/graphql/fern/docs/assets/logo.svg new file mode 100644 index 0000000..2d280fe --- /dev/null +++ b/graphql/fern/docs/assets/logo.svg @@ -0,0 +1,11 @@ + + + + + + + + + + + diff --git a/graphql/fern/docs/pages/welcome.mdx b/graphql/fern/docs/pages/welcome.mdx new file mode 100644 index 0000000..9b558d9 --- /dev/null +++ b/graphql/fern/docs/pages/welcome.mdx @@ -0,0 +1,110 @@ +--- +title: GraphQL docs example +subtitle: Generate API Reference documentation from a GraphQL schema +slug: welcome +--- + +This example demonstrates how [Fern](https://buildwithfern.com) generates interactive API Reference documentation from a GraphQL schema. It includes a sample Plant Store GraphQL API with queries, mutations, and subscriptions. + +## What's included + + + + + + + + + + + + +## Getting started + + + + +```bash +git clone https://github.com/fern-api/docs-examples.git +cp -r docs-examples/graphql my-graphql-docs +cd my-graphql-docs +``` + + + + + +```bash +npm install -g fern-api +``` + + + + + +Start a local development server with hot-reloading: + +```bash +fern docs dev +``` + +Open [http://localhost:3000](http://localhost:3000) to see your docs. + + + + + +Replace `schema.graphql` with your own GraphQL schema file and update `generators.yml`: + +```yaml title="generators.yml" +api: + specs: + - graphql: your-schema.graphql + name: Your API + origin: https://api.example.com/graphql +``` + +Update `fern.config.json` with your organization name and `docs.yml` with your desired URL. + + + + + +When you're ready to go live: + +```bash +fern generate --docs +``` + + + + +## How it works + +Fern reads your `.graphql` schema file and generates interactive API Reference documentation. The generated reference includes: + +- **Queries** with input arguments and return types +- **Mutations** with input objects and response schemas +- **Subscriptions** with event payloads +- **Types, enums, and input objects** with field-level documentation + +Navigate to the **API Reference** tab to see the generated documentation for the sample Plant Store API. + +## Learn more + + + + Configuration guide for GraphQL API References + + + Brand your documentation with colors, logos, and layouts + + diff --git a/graphql/fern/styles.css b/graphql/fern/styles.css new file mode 100644 index 0000000..154c7a8 --- /dev/null +++ b/graphql/fern/styles.css @@ -0,0 +1,10 @@ +/* Custom styles for Fern Docs Starter */ + +/* Subtle linear gradient background */ +.fern-background-image { + background-image: linear-gradient(180deg, rgba(0, 135, 0, 0.03) 0%, transparent 50%); +} + +:root.dark .fern-background-image { + background-image: linear-gradient(180deg, rgba(112, 225, 85, 0.03) 0%, transparent 50%); +} From fd65f7392adb944682556a2013c362f7cfd1f8ad Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Fri, 22 May 2026 18:52:10 +0000 Subject: [PATCH 3/5] fix: rename query operations and trim welcome page Co-Authored-By: Devin Logan --- graphql/fern/docs/pages/welcome.mdx | 92 ++--------------------------- graphql/fern/schema.graphql | 8 +-- 2 files changed, 8 insertions(+), 92 deletions(-) diff --git a/graphql/fern/docs/pages/welcome.mdx b/graphql/fern/docs/pages/welcome.mdx index 9b558d9..f40774a 100644 --- a/graphql/fern/docs/pages/welcome.mdx +++ b/graphql/fern/docs/pages/welcome.mdx @@ -4,7 +4,9 @@ subtitle: Generate API Reference documentation from a GraphQL schema slug: welcome --- -This example demonstrates how [Fern](https://buildwithfern.com) generates interactive API Reference documentation from a GraphQL schema. It includes a sample Plant Store GraphQL API with queries, mutations, and subscriptions. +This example shows how [Fern](https://buildwithfern.com) generates interactive API Reference documentation from a GraphQL schema. It uses a sample Plant Store GraphQL API with queries, mutations, and subscriptions. + +Navigate to the **API Reference** tab to see the generated documentation. ## What's included @@ -19,92 +21,6 @@ This example demonstrates how [Fern](https://buildwithfern.com) generates intera -## Getting started - - - - -```bash -git clone https://github.com/fern-api/docs-examples.git -cp -r docs-examples/graphql my-graphql-docs -cd my-graphql-docs -``` - - - - - -```bash -npm install -g fern-api -``` - - - - - -Start a local development server with hot-reloading: - -```bash -fern docs dev -``` - -Open [http://localhost:3000](http://localhost:3000) to see your docs. - - - - - -Replace `schema.graphql` with your own GraphQL schema file and update `generators.yml`: - -```yaml title="generators.yml" -api: - specs: - - graphql: your-schema.graphql - name: Your API - origin: https://api.example.com/graphql -``` - -Update `fern.config.json` with your organization name and `docs.yml` with your desired URL. - - - - - -When you're ready to go live: - -```bash -fern generate --docs -``` - - - - -## How it works - -Fern reads your `.graphql` schema file and generates interactive API Reference documentation. The generated reference includes: - -- **Queries** with input arguments and return types -- **Mutations** with input objects and response schemas -- **Subscriptions** with event payloads -- **Types, enums, and input objects** with field-level documentation - -Navigate to the **API Reference** tab to see the generated documentation for the sample Plant Store API. - ## Learn more - - - Configuration guide for GraphQL API References - - - Brand your documentation with colors, logos, and layouts - - +For configuration details, see the [GraphQL Reference documentation](https://buildwithfern.com/learn/docs/api-references/generate-graphql-ref). diff --git a/graphql/fern/schema.graphql b/graphql/fern/schema.graphql index b884b99..3b8dbf9 100644 --- a/graphql/fern/schema.graphql +++ b/graphql/fern/schema.graphql @@ -120,16 +120,16 @@ input PlantFilter { type Query { "Look up a plant by its ID." - plant(id: ID!): Plant + getPlant(id: ID!): Plant "List plants with optional filtering." - plants(filter: PlantFilter, limit: Int = 20, offset: Int = 0): [Plant!]! + listPlants(filter: PlantFilter, limit: Int = 20, offset: Int = 0): [Plant!]! "Look up an order by its ID." - order(id: ID!): Order + getOrder(id: ID!): Order "List orders, optionally filtered by status." - orders(status: OrderStatus, limit: Int = 20): [Order!]! + listOrders(status: OrderStatus, limit: Int = 20): [Order!]! } type Mutation { From 20065ea911a5f74d53a8effe321f47d7febae6fb Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Fri, 22 May 2026 18:59:42 +0000 Subject: [PATCH 4/5] feat: add API Reference landing page Co-Authored-By: Devin Logan --- graphql/fern/docs.yml | 5 ++++ .../docs/pages/api-reference-overview.mdx | 25 +++++++++++++++++++ 2 files changed, 30 insertions(+) create mode 100644 graphql/fern/docs/pages/api-reference-overview.mdx diff --git a/graphql/fern/docs.yml b/graphql/fern/docs.yml index c7c8381..1e6fa6d 100644 --- a/graphql/fern/docs.yml +++ b/graphql/fern/docs.yml @@ -28,6 +28,11 @@ navigation: icon: fa-duotone fa-house - tab: API Reference layout: + - section: Overview + contents: + - page: API reference + path: docs/pages/api-reference-overview.mdx + icon: fa-duotone fa-book - api: Plant Store GraphQL API navbar-links: diff --git a/graphql/fern/docs/pages/api-reference-overview.mdx b/graphql/fern/docs/pages/api-reference-overview.mdx new file mode 100644 index 0000000..49f0ad6 --- /dev/null +++ b/graphql/fern/docs/pages/api-reference-overview.mdx @@ -0,0 +1,25 @@ +--- +title: API reference +subtitle: Interactive documentation generated from a GraphQL schema +slug: api-reference +--- + +Fern generates interactive API Reference documentation from your GraphQL schema. This example uses a sample Plant Store GraphQL API to demonstrate the feature. + +The generated reference includes queries, mutations, subscriptions, and all associated types with field-level documentation pulled from your schema comments. + +## Plant Store GraphQL API + +Browse the API endpoints in the sidebar, or jump to a section: + + + + Read operations for plants and orders + + + Create, update, and delete operations + + + Real-time event streams + + From 61acc995f9833100e505b88faeb8b2f2f77bfa00 Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Fri, 22 May 2026 19:01:44 +0000 Subject: [PATCH 5/5] fix: link API Reference tab in welcome page Co-Authored-By: Devin Logan --- graphql/fern/docs/pages/welcome.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/graphql/fern/docs/pages/welcome.mdx b/graphql/fern/docs/pages/welcome.mdx index f40774a..7628289 100644 --- a/graphql/fern/docs/pages/welcome.mdx +++ b/graphql/fern/docs/pages/welcome.mdx @@ -6,7 +6,7 @@ slug: welcome This example shows how [Fern](https://buildwithfern.com) generates interactive API Reference documentation from a GraphQL schema. It uses a sample Plant Store GraphQL API with queries, mutations, and subscriptions. -Navigate to the **API Reference** tab to see the generated documentation. +Navigate to the [API Reference](/api-reference) tab to see the generated documentation. ## What's included