Add GraphQL API descriptions

Transform your GraphQL schema files into reference documentation by integrating them into your project. The resulting documentation shows both the high-level elements such as queries and mutations, and the details of all the individual data types.

Give your users the tools they need to make the most of your GraphQL APIs with comprehensive reference documentation. Either add individual schema files to your project alongside your other content, or use a classic catalog to showcase your GraphQL APIs alongside OpenAPI and AsyncAPI APIs.

Each GraphQL schema is served at its own URL with its own automatically generated reference sidebar, whether or not you use a sidebars.yaml file. Use a sidebars.yaml file only when you want to place the reference alongside your other content with control over its order and grouping.

Make sure you have the following:

• GraphQL schema files that use the SDL format (.graphql or .gql)

To add a GraphQL schema to your project, place the file or files in your project either at the root or in a folder. When you run your project, each schema is served as reference documentation with its own automatically generated sidebar, built from the queries, mutations, and types in the schema. For example, add a GraphQL schema file as apis/sample-schema.graphql, and then check the path /apis/sample-schema/ in your project to see the documentation.

To place the reference inside a custom sidebar alongside your other content, with control over its order and grouping, add your GraphQL schema to a sidebars.yaml file. You can also link to the reference from anywhere, such as the navbar, an in-page link, a card, or an API catalog.

To customize the API overview with title, description, and contact information, see GraphQL info configuration.

A sidebars.yaml file includes only the items you add to it, so add any files you want displayed in that sidebar, including GraphQL schema files. For more information on configuring a sidebars.yaml file for your project, see Sidebar configuration.

To add a GraphQL schema file to your project with a sidebars.yaml file, add the page and label keys with the corresponding values for the GraphQL schema file to your sidebars.yaml file, as in the following example:

- page: sample-schema.graphql
  label: Sample Schema

If you have multiple GraphQL schemas, you may want to use a group key for each description so that the different endpoints are only revealed when selected.

To add multiple GraphQL schemas using group keys, update your sidebars.yaml file, as in the following example:

- group: Sample product 1 API
  items:
    - page: sample-api-1.graphql
      label: Sample product 1 API
- group: Sample product 2 API
  items:
    - page: sample-product-2.graphql
      label: Sample product 2 API

• API catalog configuration - Organize multiple API descriptions including GraphQL schemas with catalogs for better user experience and navigation
• Sidebar navigation setup - Configure navigation structures to help users discover and access your GraphQL API documentation content
• GraphQL configuration reference - Complete customization options for GraphQL schema rendering and documentation behavior
• Navbar configuration - Add top-level links to your API references and other pages