# Fumadocs (Framework Mode, Astro): GraphQL
URL: /zh-TW/docs/astro/integrations/graphql
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/(framework)/[framework]/integrations/graphql/index.zh-TW.mdx

為 GraphQL schema 產生文件。

## 設定 [#setup]

請安裝所需的套件。

```npm
npm i @fumadocs/graphql graphql
```

### 產生樣式 [#generate-styles]

請加入下面這一行：

```css title="Tailwind CSS"
@import 'tailwindcss';
@import 'fumadocs-ui/css/neutral.css';
@import 'fumadocs-ui/css/preset.css';
/* [!code ++] */
@import '@fumadocs/graphql/css/preset.css';
```

### 設定外掛 [#configure-plugin]

建立 GraphQL 伺服器實例與 `<GraphQLPage />` 元件。

```ts tab="lib/graphql.ts"
import { createGraphQL } from '@fumadocs/graphql/server';

// 注意：這是伺服器端 API
export const graphql = createGraphQL({
  // GraphQL schema，可接受：
  // SDL 檔案／URL（包含 `extend type`）、SDL 文字、
  // 自省（introspection）結果，以及 `GraphQLSchema` 實例。
  input: ['./schema.graphql'],
});
```

```tsx tab="components/api-page.tsx"
'use client';
import { createGraphQLPage } from '@fumadocs/graphql/ui';

export const GraphQLPage = createGraphQLPage({
  playground: {
    // 在 operation 頁面上啟用互動測試區（選用）
    url: 'https://api.example.com/graphql',
  },
});
```

如需了解可用選項，請參閱 [`createGraphQL()`](/docs/astro/integrations/graphql/server) 與 [`createGraphQLPage()`](/docs/astro/integrations/graphql/api-page)。

### 產生頁面 [#generate-pages]

將 `staticSource()` 傳入您的 [`loader()`](/docs/headless/source-api/source)，即可在不寫入檔案的情況下產生頁面。

```ts title="src/lib/source.ts"
import { getCollection } from 'astro:content';
import { loader } from 'fumadocs-core/source';
import { toFumadocsSource } from '@fumadocs/astro/source';
import { graphql } from '@/lib/graphql'; // [!code ++]

export const source = loader(
  // [!code ++:6]
  {
    docs: toFumadocsSource(await getCollection('docs'), await getCollection('meta')),
    graphql: await graphql.staticSource({
      baseDir: 'graphql',
    }),
  },
  {
    baseUrl: '/docs',
    // [!code ++:2] 選用：為頁面樹中的每個頁面項目加上 query/mutation/subscription 徽章
    plugins: [graphql.loaderPlugin()],
  },
);
```

`staticSource()` 會為每個 operation 產生一個頁面，並依種類分組到資料夾中 (例如 `queries/`) 。具名型別的頁面則需[另行啟用](/docs/astro/integrations/graphql/server#includeoperations--includetypes)。

**`source` 的頁面現在分為 `docs` 與 `graphql` 兩種類型。**&#x8ACB;更新所有使用 `source` 的地方。

請在專屬的 island 中算繪 GraphQL 頁面，並在其中以文件版面配置包裹 `<GraphQLPage />`：

```astro tab="src/pages/docs/[...slug].astro"
---
import type { GetStaticPaths, InferGetStaticPropsType } from 'astro';
import Layout from '@/layouts/Layout.astro';
import { Docs } from '@/components/docs';
import { GraphQLDocs } from '@/components/graphql-docs'; // [!code ++]
import { source } from '@/lib/source';

export const prerender = true;

export const getStaticPaths = (() => {
  return source.getPages().map((page) => ({
    params: { slug: decodeURI(page.slugs.join('/')) || undefined },
    props: { page },
  }));
}) satisfies GetStaticPaths;

type Props = InferGetStaticPropsType<typeof getStaticPaths>;

const { page } = Astro.props;
const pageTree = await source.serializePageTree(source.getPageTree());
---

{/* [!code ++:13] */}
{page.type === 'graphql' && (
  <Layout title={page.data.title ?? 'My App'}>
    <GraphQLDocs
      client:load
      pathname={Astro.url.pathname}
      params={Astro.params}
      tree={pageTree}
      title={page.data.title}
      props={page.data.getGraphQLPageProps()}
    />
  </Layout>
)}
```

```tsx tab="src/components/graphql-docs.tsx"
import { type SerializedPageTree, useFumadocsLoader } from 'fumadocs-core/source/client';
import { DocsLayout } from 'fumadocs-ui/layouts/docs';
import { DocsBody, DocsPage, DocsTitle } from 'fumadocs-ui/layouts/docs/page';
import { GraphQLPage } from '@/components/api-page';
import { Provider, type ProviderProps } from '@/components/provider';
import { baseOptions } from '@/lib/layout.shared';
import type { GraphQLPageProps } from '@fumadocs/graphql/ui';

export function GraphQLDocs({
  tree,
  title,
  props,
  ...rest
}: ProviderProps & { tree: SerializedPageTree; title?: string; props: GraphQLPageProps }) {
  const data = useFumadocsLoader({ tree });

  return (
    <Provider {...rest}>
      <DocsLayout {...baseOptions()} tree={data.tree}>
        <DocsPage full>
          <DocsTitle>{title}</DocsTitle>
          <DocsBody>
            <GraphQLPage {...props} />
          </DocsBody>
        </DocsPage>
      </DocsLayout>
    </Provider>
  );
}
```

<Callout type="warn" title="請確認已完成遷移！">
繼續之前，請先執行型別檢查：

```npm
npm run types:check
```
</Callout>

## 功能 [#features]

官方 GraphQL 整合支援：

* 每個 operation (query/mutation/subscription) 各有獨立頁面，並可直接在頁面中展開檢視其使用的型別
* 引數、欄位、棄用標記、預設值，以及 `@oneOf` 輸入物件
* schema 中套用的指示詞 (directive) 及其定義
* 範例請求與回應，可自動產生，或取自[您自己的 operation](/docs/astro/integrations/graphql/server#examples)
* cURL、JavaScript、Go、Python、Java、C# 與 Rust 的程式碼範例
* 附變數表單的互動測試區，也能透過 WebSocket 或 SSE 執行[訂閱](/docs/astro/integrations/graphql/api-page#subscriptions)
* 供 LLM 使用的[頁面 Markdown](/docs/astro/integrations/graphql/server#markdown-for-llms)
* 可選的具名型別頁面，並列出該型別在整個 schema 中的使用位置

### 示範 [#demo]

請參閱 [GraphQL 範例](/docs/graphql)。