mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
mintlify[bot]
60f7b3d1f3
* docs: add GraphQL API reference setup page * docs: translate GraphQL setup page to es, fr, zh * 💅 --------- Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> Co-authored-by: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
104 lines
3.2 KiB
Plaintext
104 lines
3.2 KiB
Plaintext
---
|
|
title: "GraphQL setup"
|
|
description: "Generate reference pages for your GraphQL API from a schema definition file, with linked types and example queries, mutations, and responses."
|
|
keywords: ["graphql", "schema", "sdl"]
|
|
---
|
|
|
|
## 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.
|
|
|
|
```graphql schema.graphql
|
|
"An object with a stable identifier."
|
|
interface Node {
|
|
id: ID!
|
|
}
|
|
|
|
type Organization implements Node {
|
|
id: ID!
|
|
name: String!
|
|
}
|
|
|
|
type Query {
|
|
organization(id: ID!): Organization
|
|
}
|
|
```
|
|
|
|
## Auto-populate GraphQL pages
|
|
|
|
To automatically generate pages for every query, mutation, and type in your schema, add a `graphql` property to a tab in your `docs.json`. Mintlify parses the schema and creates a page for each operation and named type.
|
|
|
|
<CodeGroup>
|
|
|
|
```json Local file
|
|
"navigation": {
|
|
"tabs": [
|
|
{
|
|
"tab": "GraphQL API",
|
|
"graphql": "schema.graphql"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
```json Remote URL
|
|
"navigation": {
|
|
"tabs": [
|
|
{
|
|
"tab": "GraphQL API",
|
|
"graphql": "https://example.com/schema.graphql"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
```json Custom directory
|
|
"navigation": {
|
|
"tabs": [
|
|
{
|
|
"tab": "GraphQL API",
|
|
"graphql": {
|
|
"source": "schema.graphql",
|
|
"directory": "api/graphql"
|
|
}
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
</CodeGroup>
|
|
|
|
The `graphql` property accepts either a string (a local path or HTTPS URL) or an object with the following fields.
|
|
|
|
<Note>
|
|
You must declare `graphql` on a [tab](/organize/navigation#tabs). A tab with `graphql` may include `groups`, but no other navigation structures, such as `pages`, `versions`, or `languages`. It also cannot include an `openapi` or `asyncapi` property.
|
|
</Note>
|
|
|
|
<ParamField path="source" type="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.
|
|
</ParamField>
|
|
|
|
<ParamField path="directory" type="string">
|
|
The directory to store generated pages. Defaults to `graphql-reference`.
|
|
</ParamField>
|
|
|
|
## Generated pages
|
|
|
|
Mintlify organizes generated pages into three sections under the tab 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, union, or scalar type.
|
|
|
|
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.
|
|
|
|
## 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.
|