無頭式

概覽

除了 @fumadocs/asyncapi/ui 之外，其餘皆為無頭式。

路徑	模組
`@fumadocs/asyncapi`	頁面：文件、其伺服器，以及您的元件
`@fumadocs/asyncapi/operation`	單一 operation：其頻道、參數、訊息與回覆
`@fumadocs/asyncapi/playground`	operation 頻道上的工作階段

頁面

createAsyncAPIRenderer() 會接收您的元件，並回傳 <AsyncAPIPage />，該元件接受所產生頁面的 props。

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 schema
`Layout`	選用，用來包覆已渲染的 operation

Hooks

頁面底下的元件可以讀取頁面的狀態。

Hook	回傳值
`useAsyncAPI()`	已解參照的文件 (`doc`) 與頁面選項
`useComponents()`	傳入頁面的元件
`useServer()`	伺服器列表、目前選取的伺服器及其變數
`useRenderContext()`	頁面的算繪選項，例如 `content`

若要自行算繪 operation，請改為掛載 <AsyncAPIProvider document={bundled} components={...} />，以取代 createAsyncAPIRenderer()。

Operation

<OperationProvider /> 只會推導一次 operation 的詳細資訊：套用 traits，並解析其頻道、參數、訊息與回覆。

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>
    </>
  );
}

Hook	回傳值
`useOperation()`	已解析詳細資訊的 operation
`useOperationSecurity()`	所選伺服器與該 operation 的安全性方案 (兩者皆會套用)
`useChannelMessages()`	讀者在該頻道上接收與傳送的訊息，涵蓋該頻道的所有 operation

屬性

型別

訊息範例取自文件本身，或依據其 schema 產生。

屬性

型別

互動測試區

usePlayground() 會在 <OperationProvider /> 之下，透過傳輸層連線至 operation 的頻道。

'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>
      ))}
    </>
  );
}

位址參數、query 與驗證輸入都屬於表單 stf，url 會隨其值更新。
連線期間即可使用 send，除非該連線僅能接收訊息。
收到的訊息會與頻道上各訊息的酬載進行比對，entry.message 即為對應的文件化訊息；二進位訊息則存放於 entry.binary。

屬性

型別

傳輸層

傳輸層負責連線至某個協定的伺服器，範例請參考 MQTT 範例。系統會依序從 usePlayground() 的 transports、頁面的 playground.transports 中選取，最後才使用內建的 WebSocket 傳輸層。

usePlaygroundTransport() 接受相同的 transports，並回傳所選伺服器對應的傳輸層；若沒有任何傳輸層能連線至該伺服器，則回傳 undefined。

屬性

型別

connect() 會透過 events 回報：open()、message(data) (內容為文字或 ArrayBuffer) ，以及 close() 或 error()，後兩者會結束連線。

屬性

型別

概覽複製錨點連結

頁面複製錨點連結

Hooks複製錨點連結

Operation複製錨點連結

互動測試區複製錨點連結

傳輸層複製錨點連結

本頁目錄

概覽

頁面

Hooks

Operation

互動測試區

傳輸層