手書きの API ページ

仕様を用意せずに MDX でエンドポイントをドキュメント化しても、メソッドとパス、Try it パネル、リクエストサンプル、固定表示される例を利用できます。

すべての API に OpenAPI 仕様があるわけではなく、手書きのほうが読みやすいエンドポイントもあります。api フロントマターを持つページは 1 つのエンドポイントをドキュメント化します。ページのフィールドがリクエストとレスポンスを記述し、Blume はそれをもとに OpenAPI リファレンスページの残りの部分を構築します。上部にはメソッドとパスが表示されます。コンテンツの横の列には Try it パネルとリクエストサンプルが並び、その下にリクエストとレスポンスの例が固定表示されます。

---
title: Create a user
api: POST /workspaces/{workspaceId}/users
---

Creates a user and sends them an invite.

<ParamField path="workspaceId" type="string" required>
  The workspace to add the user to.
</ParamField>

<ParamField body="email" type="string" required placeholder="ada@example.com">
  The user's email address.
</ParamField>

<ParamField body="role" type="string" default="member">
  One of `owner`, `admin`, or `member`.
</ParamField>

<ResponseField name="id" type="string" required>
  The new user's ID.
</ResponseField>

<ResponseExample>

```json 201
{ "id": "usr_8f2k", "status": "invited" }
```

</ResponseExample>

api には HTTP メソッドと、パスまたは完全な URL を指定します。パスパラメーターは {workspaceId} のように波かっこで囲んで記述し、対応する path フィールドの値が入ります。GET https://api.acme.com/v1/users のような完全な URL を指定した場合は、記述したとおりの URL にリクエストが送信されます。パスを指定した場合は、サイトの api.server と結合されます。

プレイグラウンドとサンプル

仕様内のオペレーションのパラメーターと同じように、ページの ParamField は Try it パネルの入力項目になります。path、query、header フィールドはパラメーターになり、body フィールドは JSON ボディを構成します。フィールドの中にネストされたフィールド（その Expandable 内のもの）は、オブジェクトのプロパティになります。type が string[] の場合は配列として扱われ、enum<string> のように JSON の型ではないものは文字列として送信されます。フィールドの default はボディの初期値になり、placeholder はサンプルに表示される例の値になります。

パネルの横には、cURL、JavaScript、Python のリクエストサンプルが表示されます。独自の RequestExample を持つページでは、これらの代わりにその内容が表示されます。

さらに 2 つのフロントマターキーでページを調整できます。

authMethod は、エンドポイントの認証方法を設定します。bearer、basic、key（ヘッダーで送る API キー）、none のいずれかを指定します。この設定はサイトの api.auth より優先されます。
playground は、ページに表示する内容を設定します。Try it パネルとサンプルを表示する interactive（デフォルト）、サンプルのみを表示する simple、どちらも表示しない none のいずれかを指定します。どの場合も、メソッド、パス、例は表示されたままです。

サイトのデフォルト

blume.config.ts の api では、すべてのエンドポイントページに共通する設定を指定します。

export default defineConfig({
  api: {
    server: "https://api.acme.com/v1",
    auth: { method: "key", name: "x-api-key" },
    playground: { proxy: true },
  },
});

server は、api のパスと結合されるベース URL です。
auth は、ページで authMethod を設定していない場合に使われるリクエストの認証方法です。method には bearer、basic、key、none のいずれかを指定し、name には API キーを入れるヘッダーを指定します（デフォルトは x-api-key）。auth を指定しない場合、ページは認証情報を送信しません。
playground には、OpenAPI リファレンスの playground オプションと同じ値を指定できます。false を指定すると、すべてのページで Try it パネルが非表示になります。proxy を指定すると、パネルからのリクエストが CORS プロキシ経由で送信されます。値には独自のプロキシの URL を指定するか、true を指定して Blume の組み込みプロキシを使用します。組み込みプロキシを使うにはサーバー出力が必要です。また、組み込みプロキシの転送先は、server のオリジンと、api フロントマターに記述された完全な URL のオリジンに限られます。

ページのレイアウト、フィールド、例には他のページと同じコンポーネントが使われています。そのため、ページの Markdown コピーには各フィールドが一覧表示され、検索でも他のページと同じようにインデックスされます。

フロントマターキーとコンポーネントの props は Mintlify のものと同じなので、Mintlify 向けに書かれたページはそのまま動作します。