Skip to main content

​
Add a GraphQL schema

To create pages for your GraphQL API, you need a valid GraphQL schema in SDL (Schema Definition Language) format. Store the schema in your documentation repository or host it at an HTTPS URL that Mintlify can fetch.
schema.graphql

​
Auto-populate GraphQL pages

To automatically generate pages for every query, mutation, and type in your schema, add a graphql property to a tab or group in your docs.json. Mintlify parses the schema and creates a page for each operation and named type.
The graphql property accepts either a string (a local path or HTTPS URL) or an object with the following fields.
You can declare graphql only on a tab or a group.A tab with graphql may include groups, but no other navigation structures, such as pages, versions, or languages.A group with graphql may include pages.
​
string
required
A local path to an SDL file in your documentation repository or an HTTPS URL to a hosted SDL file. Does not accept HTTP URLs.
​
string
The directory to store generated pages. Defaults to graphql-reference.

​
Generated pages

Mintlify organizes generated pages into three sections under the tab or group you configured:
  • Queries: One page per field on your Query root type.
  • Mutations: One page per field on your Mutation root type.
  • Types: One page per named object, input, enum, interface, or union type.
On a tab, the sections appear after any groups you define. On a group, they appear as nested groups after any pages you list. Each operation page shows the field description, arguments, return type, and links to any referenced types. Query and mutation pages also include a generated example operation, the required variables, and a sample JSON response. Type pages render the schema definition read-only, with linked field types so readers can navigate the graph.

​
Select specific operations and types

To build a curated reference instead of generating every page, list selectors in the pages array of a group that declares graphql. You can also list them in any group nested under a tab or group that declares graphql. Tabs with graphql cannot include pages, so place selectors in a group inside the tab. Mintlify generates a page only for each selected operation or type.
A selector is a kind followed by a name, separated by a space:
  • QUERY <field>: A field on your Query root type.
  • MUTATION <field>: A field on your Mutation root type.
  • TYPE <name>: A named object, input, enum, interface, or union type.
Selector kinds must be uppercase. Use a dotted path, such as MUTATION cart.createCart, to select an operation nested under a namespace field. TYPE selectors do not accept dotted paths. The sidebar labels a nested operation with its last segment, so MUTATION cart.createCart appears as createCart. The page URL keeps the full path and ends in cart/createCart. If any page under a tab or group with graphql is a selector, Mintlify skips generating the full Queries, Mutations, and Types sections for it. Regular page paths in the same pages array work as usual. In a curated reference, query and mutation pages link only to the type pages that your selectors generate. To link a type referenced by a selected operation, add a TYPE selector for that type. If a selector does not match anything in your schema, the build fails with an error that names the missing operation or type.

​
Deprecations

Fields and arguments that you mark with @deprecated in your schema display as deprecated on the generated pages. If you provide a deprecation reason, it appears next to the field.

​
Update your documentation

Mintlify regenerates GraphQL reference pages when you run mint dev or when you push changes to your documentation repository. If your schema is hosted at an HTTPS URL, updates to the schema regenerate on the next build.

Related topics

Migrate from another platformSEOHost docs at a subpath