# GraphQL 设置 (/zh/api-playground/graphql-setup)

<!-- agent-signals: reading_time_min: 1 · est_tokens: 763 · updated: 2026-07-30 -->
Related: [操作台](/zh/api-playground/overview.md), [OpenAPI 设置](/zh/api-playground/openapi-setup.md), [复杂数据类型](/zh/api-playground/complex-data-types.md), [添加 SDK 示例](/zh/api-playground/adding-sdk-examples.md), [管理页面可见性](/zh/api-playground/managing-page-visibility.md), [多种响应](/zh/api-playground/multiple-responses.md)

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

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

```graphql title="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 页面 [#自动填充-graphql-页面]
</div>

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

<CodeGroup>
  <CodeBlockTabs defaultValue="Local file" groupId="custom-directory+local-file+remote-url">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="Local file">
        Local file
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="Remote URL">
        Remote URL
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="Custom directory">
        Custom directory
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="Local file">
      ```json  
      "navigation": {
        "tabs": [
          {
            "tab": "GraphQL API",
            "graphql": "schema.graphql"
          }
        ]
      }
      ```
    </CodeBlockTab>

    <CodeBlockTab value="Remote URL">
      ```json  
      "navigation": {
        "tabs": [
          {
            "tab": "GraphQL API",
            "graphql": "https://example.com/schema.graphql"
          }
        ]
      }
      ```
    </CodeBlockTab>

    <CodeBlockTab value="Custom directory">
      ```json  
      "navigation": {
        "tabs": [
          {
            "tab": "GraphQL API",
            "graphql": {
              "source": "schema.graphql",
              "directory": "api/graphql"
            }
          }
        ]
      }
      ```
    </CodeBlockTab>
  </CodeBlockTabs>
</CodeGroup>

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

<ParamField path="source" type="string">
  指向文档仓库中 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 的更新会在下一次构建时被采纳。