# Fumadocs (Framework Mode, Waku): ヘッドレス
URL: /ja/docs/waku/integrations/asyncapi/headless
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/(framework)/[framework]/integrations/asyncapi/headless.ja.mdx

UIを含まない、AsyncAPIページの状態とロジック。

## 概要 [#overview]

`@fumadocs/asyncapi/ui` 以外はすべてヘッドレスです。

| パス                              | モジュール                         |
| ------------------------------- | ----------------------------- |
| `@fumadocs/asyncapi`            | ページ：ドキュメント、サーバー、独自のコンポーネント    |
| `@fumadocs/asyncapi/operation`  | オペレーション：チャンネル、パラメーター、メッセージ、応答 |
| `@fumadocs/asyncapi/playground` | オペレーションのチャンネル上のセッション          |

## ページ [#page]

`createAsyncAPIRenderer()` は独自のコンポーネントを受け取り、`<AsyncAPIPage />` を返します。このコンポーネントは、生成されたページの props を受け取ります。

```tsx title="components/api-page.tsx"
'use client';
import { type CodeBlockProps, createAsyncAPIRenderer } from '@fumadocs/asyncapi';
import { Operation } from '@/components/my-operation';
import { SchemaUI } from '@/components/my-schema';

export const AsyncAPIPage = createAsyncAPIRenderer({
  components: {
    Operation,
    SchemaUI,
    CodeBlock({ lang, code }: CodeBlockProps) {
      return (
        <pre>
          <code className={`language-${lang}`}>{code}</code>
        </pre>
      );
    },
  },
});
```

| コンポーネント     | レンダリング対象                                       |
| ----------- | ---------------------------------------------- |
| `Operation` | ページ内の各オペレーション。[Operation](#operation)を参照してください |
| `SchemaUI`  | パラメーター、ヘッダー、メッセージペイロードのJSONスキーマ                |
| `Layout`    | 省略可能。レンダリングされたオペレーションをラップします                   |

### フック [#hooks]

ページ配下のコンポーネントは、以下のフックでページの状態を読み取ります。

| フック                  | 戻り値                             |
| -------------------- | ------------------------------- |
| `useAsyncAPI()`      | 参照解決済みのドキュメント (`doc`) とページオプション |
| `useComponents()`    | ページに渡されたコンポーネント                 |
| `useServer()`        | サーバー一覧、選択中のサーバー、およびその変数         |
| `useRenderContext()` | `content` などのページのレンダリングオプション    |

オペレーションを独自にレンダリングするには、`createAsyncAPIRenderer()` の代わりに `<AsyncAPIProvider document={bundled} components={...} />` をマウントしてください。

## オペレーション [#operation]

`<OperationProvider />` は、オペレーションの詳細を一度だけ導出します。この際にトレイトが適用され、オペレーションのチャンネル、パラメーター、メッセージ、応答が解決されます。

```tsx title="components/my-operation.tsx"
'use client';
import {
  OperationProvider,
  type PageOperationProps,
  useOperation,
  useOperationSecurity,
} from '@fumadocs/asyncapi/operation';

export function Operation(props: PageOperationProps) {
  return (
    <OperationProvider {...props}>
      <Content />
    </OperationProvider>
  );
}

function Content() {
  const { title, channel, parameters, messages } = useOperation();
  const security = useOperationSecurity();

  return (
    <>
      <h2>{title}</h2>
      <code>{channel.address}</code>
      <ul>
        {parameters.map((param) => (
          <li key={param.name}>{param.name}</li>
        ))}
      </ul>
      {messages.map((message) => (
        <section key={message.id}>
          <h3>{message.name}</h3>
          {message.examples.map((example) => (
            <pre key={example.id}>{JSON.stringify(example.payload, null, 2)}</pre>
          ))}
        </section>
      ))}
      <p>{security.operation.map((item) => item.id).join(', ')}</p>
    </>
  );
}
```

| フック                      | 戻り値                                      |
| ------------------------ | ---------------------------------------- |
| `useOperation()`         | 詳細が解決済みのオペレーション                          |
| `useOperationSecurity()` | 選択中のサーバーとオペレーションのセキュリティスキーム (両方が適用されます)  |
| `useChannelMessages()`   | チャンネルの全オペレーションを通じて読者が受信・送信するメッセージ        |

### OperationInfo

| Prop           | Type                                    | Description                                                                      |
| -------------- | --------------------------------------- | -------------------------------------------------------------------------------- |
| `id`           | `string`                                |                                                                                  |
| `action`       | `"receive" \| "send"`                   | the action of the application described by the document, readers do the opposite |
| `operation`    | `OperationObject`                       | resolved, with traits applied                                                    |
| `channel`      | `ChannelObject`                         |                                                                                  |
| `title`        | `string`                                |                                                                                  |
| `description?` | `string \| undefined`                   |                                                                                  |
| `parameters`   | `Operation.OperationParameter[]`        | parameters of the channel address                                                |
| `messages`     | `Operation.OperationMessage[]`          |                                                                                  |
| `reply?`       | `Operation.OperationReply \| undefined` |                                                                                  |

メッセージの例は、ドキュメントから取得されるか、そのスキーマから生成されます。

### OperationMessage

| Prop           | Type                                   | Description                                                   |
| -------------- | -------------------------------------- | ------------------------------------------------------------- |
| `id`           | `string`                               | the key of message in its channel, unique in the operation    |
| `name`         | `string`                               | display name                                                  |
| `message`      | `MessageObject`                        | resolved, with traits applied                                 |
| `contentType?` | `string \| undefined`                  | falls back to the `defaultContentType` of document            |
| `received`     | `boolean`                              | sent by the application to readers, otherwise readers send it |
| `headers?`     | `Operation.MessageSchema \| undefined` |                                                               |
| `payload?`     | `Operation.MessageSchema \| undefined` |                                                               |
| `examples`     | `ExampleMessageItem[]`                 | example messages, generated from its schemas when it has none |

## プレイグラウンド [#playground]

`usePlayground()` は `<OperationProvider />` の配下で、トランスポートを使ってオペレーションのチャンネルに接続します。

```tsx
'use client';
import { usePlayground } from '@fumadocs/asyncapi/playground';
import { mqttTransport } from '@/lib/mqtt-transport';

export function Playground() {
  const { url, status, connect, disconnect, send, log } = usePlayground({
    // ページの `playground.transports` に加えて使用されます
    transports: { mqtt: mqttTransport },
  });
  if (!url) return null; // サーバーに対応するトランスポートがない場合

  return (
    <>
      <button onClick={status === 'closed' ? connect : disconnect}>{status}</button>
      {send && <button onClick={() => send('{"type":"ping"}')}>Ping</button>}
      {log.map((entry) => (
        <p key={entry.id}>
          {entry.type} {entry.message?.name} {entry.data}
        </p>
      ))}
    </>
  );
}
```

* アドレスのパラメーター、クエリ、認証の入力はフォーム `stf` で管理され、`url` はその値に連動して更新されます。
* `send` は接続中に使用できます。ただし、受信専用の接続では使用できません。
* 受信したメッセージは、チャンネル上の各メッセージのペイロードと照合され、一致したドキュメント上のメッセージが `entry.message` に入ります。バイナリメッセージは `entry.binary` に入ります。

### Playground

| Prop         | Type                                                                                         | Description                                                                                                         |
| ------------ | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `stf`        | `Stf`                                                                                        | the form of PlaygroundValues                                                                                        |
| `transport?` | `PlaygroundModule.PlaygroundTransport \| undefined`                                          | the transport connecting to the selected server, `undefined` when none does                                         |
| `url?`       | `string \| undefined`                                                                        | the URL to connect with the values of form, `undefined` without a transport                                         |
| `status`     | `PlaygroundModule.ConnectionStatus`                                                          |                                                                                                                     |
| `connect`    | `() => void`                                                                                 |                                                                                                                     |
| `disconnect` | `() => void`                                                                                 |                                                                                                                     |
| `send?`      | `((data: string \| ArrayBuffer, message?: Operation.OperationMessage) => void) \| undefined` | send a message, with the documented message it is. Absent until connected, and when the connection can only receive |
| `log`        | `PlaygroundModule.LogEntry[]`                                                                |                                                                                                                     |
| `clearLog`   | `() => void`                                                                                 |                                                                                                                     |

### トランスポート [#transports]

トランスポートは、プロトコルのサーバーへの接続を担います ([MQTT の例](/docs/waku/integrations/asyncapi/api-page#custom-transports)を参照してください) 。トランスポートは `usePlayground()` の `transports`、ページの `playground.transports`、組み込みの WebSocket トランスポートの順に選択されます。

`usePlaygroundTransport()` は同じ `transports` を受け取り、選択中のサーバーに対応するトランスポートを返します。そのサーバーに接続できるトランスポートがない場合は `undefined` を返します。

### PlaygroundTransport

| Prop      | Type                                                                                                                         | Description                                                                                             |
| --------- | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| `auth?`   | `((scheme: SecuritySchemeObject) => boolean) \| undefined`                                                                   | security schemes it can apply besides API keys in the query, they become inputs of the connection panel |
| `connect` | `(target: PlaygroundModule.ConnectTarget, events: PlaygroundModule.TransportEvents) => PlaygroundModule.TransportConnection` |                                                                                                         |

`connect()` は `events` に対して、`open()`、テキストまたは `ArrayBuffer` を渡す `message(data)`、接続を終了させる `close()` または `error()` を通知します。

### ConnectTarget

| Prop      | Type                                                                                            | Description                                                   |
| --------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| `url`     | `string`                                                                                        | server URL, address and query, for URL-based protocols        |
| `server`  | `ServerObject`                                                                                  |                                                               |
| `address` | `string`                                                                                        | the channel address with its parameters                       |
| `query`   | `Record<string, unknown>`                                                                       |                                                               |
| `auth`    | `{ scheme: SecuritySchemeObject; value: string \| { username: string; password: string; }; }[]` | values of the auth inputs, for the schemes accepted by `auth` |