GraphQL

To describe your GraphQL API, make sure you have a valid GraphQL schema file that follows the 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:

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:

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

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:

or type-level:

Navigation Customization

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:

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:

1. Directly as string values:

2. Define scopes as enum via OpenDocsScope:

Sort

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

or if you want to sort by groups:

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

you can use different sort stacks too:

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.