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

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

````mdx docs/users/create.mdx lineNumbers
---
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`](#site-defaults) と結合されます。

## プレイグラウンドとサンプル [#the-playground-and-samples]

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

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

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

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

## サイトのデフォルト [#site-defaults]

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

```ts blume.config.ts lineNumbers
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 オプション](/ja/docs/references/openapi#try-it-playground)と同じ値を指定できます。`false` を指定すると、すべてのページで Try it パネルが非表示になります。`proxy` を指定すると、パネルからのリクエストが CORS プロキシ経由で送信されます。値には独自のプロキシの URL を指定するか、`true` を指定して Blume の組み込みプロキシを使用します。組み込みプロキシを使うには[サーバー出力](/ja/docs/deployment#server-rendering)が必要です。また、組み込みプロキシの転送先は、`server` のオリジンと、`api` フロントマターに記述された完全な URL のオリジンに限られます。

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

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