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..1e6fa6d --- /dev/null +++ b/graphql/fern/docs.yml @@ -0,0 +1,68 @@ +# yaml-language-server: $schema=https://schema.buildwithfern.dev/docs-yml.json + +instances: + - url: graphql.docs.buildwithfern.com + +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: + - tab: home + layout: + - section: Get started + contents: + - page: Welcome + path: docs/pages/welcome.mdx + 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: + - 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: + dark: "#70E155" + light: "#008700" + background: + dark: "#111113" + light: "#FFFFFF" + +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/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 + + diff --git a/graphql/fern/docs/pages/welcome.mdx b/graphql/fern/docs/pages/welcome.mdx new file mode 100644 index 0000000..7628289 --- /dev/null +++ b/graphql/fern/docs/pages/welcome.mdx @@ -0,0 +1,26 @@ +--- +title: GraphQL docs example +subtitle: Generate API Reference documentation from a GraphQL schema +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](/api-reference) tab to see the generated documentation. + +## What's included + + + + + + + + + + + + +## Learn more + +For configuration details, see the [GraphQL Reference documentation](https://buildwithfern.com/learn/docs/api-references/generate-graphql-ref). 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..3b8dbf9 --- /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." + getPlant(id: ID!): Plant + + "List plants with optional filtering." + listPlants(filter: PlantFilter, limit: Int = 20, offset: Int = 0): [Plant!]! + + "Look up an order by its ID." + getOrder(id: ID!): Order + + "List orders, optionally filtered by status." + listOrders(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! +} 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%); +}