GraphQL

API Pages

GraphQL

Reference GraphQL schema in your docs pages

To describe your GraphQL API, make sure you have a valid GraphQL schema file that follows the GraphQL specification.

Your document must follow GraphQL specification.

Configuration Quickstart

The fastest way to get started with GraphQL is to add a graphql field to api in the settings file. This field can contain either the path to a GraphQL schema file in your docs repo, or the URL of a hosted GraphQL schema:

{
    // ... rest of settings
    "api": {
        "graphql": {
            "source": "./api/graphql/schema.graphql",
            "route": "docs/api/graphql"
        }
    },
}

This will create a new route based on your GraphQL specification at docs/api/graphql/*.

Multi Spec Configuration

Creating multi API specs for more advanced use cases is also possible:

{
    // ... rest of settings
    "api": {
        "graphql": [
          {
            "source": "./api/graphql/schema.graphql",
            "route": "docs/api/graphql"
          },
          {
            "source": "./api/graphql/admin.graphql",
            "route": "docs/api/graphql/admin"
          }
        ]
    }
}

Thanks to this configuration, you'll have two routes: docs/api/graphql/* and docs/api/graphql/admin/*.

API Docs Generation Guides

The generator automatically creates documentation based on your GraphQL schema
By default, groups types by their categories:
- Queries, Mutations, Subscriptions
- Objects, Inputs, Interfaces, Enums, Scalars
Links related types and operations together

All defaults can be overridden using the optional docs directives

Docs Directives

The documentation system provides two directives:

@docs - Schema-level directive for global settings like routing and sorting
@doc - Type-level directive for customizing queries, mutations, objects, enums, and scalars

You can define global settings like:

# Global schema configuration
extend schema @docs(
    # schema-level settings
)

or type-level:

type Query {
    user(id: ID!): User 
    @doc(
        # type-level settings for operation types
    )
}

type User @doc(
    # type-level settings for other types
) {
    id: ID!
    name: String!
}

The @doc directive is optional. If not specified, the generator will automatically group types by their categories (Queries, Mutations, Objects, etc.).

While the generator automatically organizes your schema, you can customize the navigation structure using the optional @doc directive. This directive allows you to override the default grouping and organize your types and operations into custom groups or manage URLs.

Here's an example of how to use the @doc directive:

1type Query
2type Mutation
3
4extend schema @docs(
5    group: ["API & Reference"]
6    # above `group` is the root that every node will inherit
7)
8
9extend type Query @doc(
10    group: ["Users", "Queries"],
11    path: "users/queries"
12    # `group` and `path` will be inherited by all operations in this type
13) {
14    getUser(id: ID!): User
15    @doc(
16        path: "get"
17    )
18    # inherits `group` and `path` from Query + adds "get" to `path` 
19}
20
21extend type Query @doc(
22    group: ["Todos", "Queries"],
23    path: "todos/queries"
24    # `group` and `path` will be inherited by all operations in this type
25    # NOTE: it's a different type from the previous one, so it can have its own `group` and `path`
26) {
27    deleteTodo(id: ID!): Boolean!
28    # if we do not specify `@doc` for operation it will automatically get operation name as `path`
29}
30
31extend type Mutation @doc(
32    group: ["Users", "Mutations"],
33    path: "users/mutations"
34) {
35    createUser(createUserInput!): User
36    # if we do not specify `@doc` for operation it will automatically get operation name as `path`
37}
38
39type User @doc(
40    group: ["Users", "Objects"],
41    # we can declare `group` for the type itself
42) {
43    id: ID!
44    name: String!
45    email: String!
46}
47
48input createUserInput @doc(
49    group: ["Users", "Inputs"],
50    # we can declare `group` for the input type itself
51) {
52    name: String!
53    email: String!
54}
55
56scalar Email @doc(
57    group: ["Scalars"]
58    # we can declare `group` for the scalar type itself too
59)

Tip

Check out our GraphQL docs directives sample.

Scopes

Scopes indicate required permissions in the documentation. Use the scopes parameter in the @doc directive to add this information to the docs pages.

You can define scopes in two ways:

Directly as string values:

type Query {
    user(id: ID!): User
    @doc(
        scopes: ["user:read"]
    )
}

Define scopes as enum via OpenDocsScope:

extend enum OpenDocsScope {
    USER_READ @scope(value: "user:read")

    USER_WRITE @scope(value: "user:write")
}


type Mutation {
    userAdd(input: UserWrite!): User
    @doc(
        scopes: [USER_READ, USER_WRITE]
    )
}

CAUTION

This DO NOT protect your API, its only for docs purposes.

Sort

Customize the order in the documentation using the sort parameter in the @docs directive:

extend schema @docs(
    sort: [
        {
            node: "scalar",
        },
        {
            node: "enum",
        },
        {
            node: "interface",
        },
        {
            node: "input",
        },
        {
            node: "object",
        },
        {
            node: "union",
        },
        {
            node: "query",
        },
        {
            node: "mutation",
        },
        {
            node: "subscription"
        }
    ]
)

Info

Default sort order is: query, mutation, subscription, object, interface, union, input and scalar

or if you want to sort by groups:

extend schema @docs(
    sort: [
        {
            group: ["Users", "Mutations", "Objects", "Inputs", "Scalars"],
        },
        {
            group: ["Todos", "Mutations", "Objects", "Inputs", "Scalars"],
        }
    ]
)

Important

Please make sure your Queries/Mutations/Subscriptions use extend type syntax, otherwise they will not be grouped correctly.

if you dont want to repeat a sort patterns you can use sortStack:

extend schema @docs(
    sortStack: [
      ["Queries", "Mutations", "Objects", "Inputs", "Scalars"], #0
    ],
    sort: [
        {
            group: ["Users"], # + ["Queries", "Mutations" ...] 
            stack: 0 
        },
        {
            group: ["Todos"], # + ...
            # if not specified it will get sort #0 automatically
        }
    ]
)

sortStack

Helps reduce boilerplate of declaring a group order.

you can use different sort stacks too:


extend schema @docs(
    sortStack: [
      # ... #0
      ["Scalars", "Objects", "Inputs"], #1
    ],
    sort: [
        #...
         {
            group: ["GraphQL Types"] # + ["Scalars", "Objects", "Inputs"],
+
            stack: 1
        }
    ]
)

API Docs Demo

You can also check out our interactive API Docs Demo to see these features in action and experiment with different GraphQL configurations in real-time.

GraphQL Samples

Learn how to setup GraphQL pages.

OpenAPI UI Components

GraphQL

Reference GraphQL schema in your docs pages

Configuration Quickstart

Multi Spec Configuration

API Docs Generation Guides

Docs Directives

Navigation Customization

Scopes

Sort

API Docs Demo

GraphQL Samples