mintlify__docs/zh/api-playground/graphql-setup.mdx

---
title: "GraphQL 设置"
description: "从 schema 定义文件为你的 GraphQL API 生成参考页面，包含相互链接的类型以及示例 query、mutation 和响应。"
keywords: ["graphql", "schema", "sdl"]
---

<div id="add-a-graphql-schema">
  ## 添加 GraphQL schema
</div>

要为你的 GraphQL API 创建页面，你需要一个采用 SDL (Schema Definition Language) 格式的有效 GraphQL schema。将 schema 存储在你的文档仓库中，或托管在 Mintlify 可访问的 HTTPS URL 上。

```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
}
```

<div id="auto-populate-graphql-pages">
  ## 自动填充 GraphQL 页面
</div>

要为 schema 中的每个 query、mutation 和 type 自动生成页面，请在 `docs.json` 中的某个 tab 添加 `graphql` 属性。Mintlify 会解析 schema，并为每个操作和命名类型创建一个页面。

<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>

`graphql` 属性可接受字符串 (本地路径或 HTTPS URL) ，或包含以下字段的对象：

<ParamField path="source" type="string" required>
  指向文档仓库中 SDL 文件的本地路径，或指向已托管 SDL 文件的 HTTPS URL。不接受 HTTP URL。
</ParamField>

<ParamField path="directory" type="string">
  生成页面所存放的目录。默认值为 `graphql-reference`。
</ParamField>

<Note>
  GraphQL 源仅在 tab 上受支持。声明了 `graphql` 的 tab 不能同时声明 `openapi` 或 `asyncapi`。
</Note>

<div id="generated-pages">
  ## 生成的页面
</div>

Mintlify 会将生成的页面组织到你所配置的 tab 下的三个部分中：

- **Queries** — 为 `Query` 根类型的每个字段生成一个页面。
- **Mutations** — 为 `Mutation` 根类型的每个字段生成一个页面。
- **Types** — 为每个命名的 object、input、enum、interface、union 或 scalar 类型生成一个页面。

每个操作页面会显示字段描述、参数、返回类型以及指向所引用类型的链接。Query 和 mutation 页面还会在侧边面板中 (在移动端则内联显示) 包含自动生成的示例操作、所需变量以及示例 JSON 响应。

Type 页面以只读方式渲染 schema 定义，并为字段类型提供链接，方便读者浏览整个 graph。

<div id="deprecations">
  ## 弃用
</div>

在你的 schema 中被标记为 `@deprecated` 的字段和参数，会在生成的页面上被标记为已弃用。如果提供了弃用原因，将显示在该字段旁边。

<div id="update-your-documentation">
  ## 更新你的文档
</div>

当你运行 `mint dev` 或将更改推送到文档仓库时，Mintlify 会重新生成 GraphQL 参考页面。如果你的 schema 托管在 HTTPS URL 上，schema 的更新会在下一次构建时被采纳。