# レスポンスから作る仕様 (/ja/docs/specs/specs-from-traffic)

仕様より先に、リクエストがあることはよくあります。誰かが読み込んだコレクションや、APIを調べるうちに試した呼び出しなどです。
**レスポンスから作る仕様**は、それらをOpenAPIドキュメントに変換します。各リクエストは、最後に得たレスポンスをもとに記述されたオペレーションになります。
パスとパラメータ、送信したボディ、そしてレスポンスのボディのJSON Schemaと例が含まれます。すでにある仕様に追加することもでき、その場合は足りないものだけが加わります。

## フォルダを記述する [#documenting-a-folder]

<Steps>
<Step>

記述したいリクエストを送信して、それぞれにレスポンスがある状態にします。たとえばAlpenglowでは、**Catalog**フォルダのリクエストを送信します。

</Step>
<Step>

リクエストのサイドバーでフォルダを右クリックして、<strong>OpenAPI仕様に記述…</strong>を選択します。ワークスペース全体を記述するには、仕様のサイドバーで<strong>+</strong> › <strong>レスポンスから新規仕様…</strong>、空の仕様ページで<strong>レスポンスから…</strong>、またはコマンドパレットで<strong>レスポンスから新規仕様…</strong>を選択します。

</Step>
<Step>

**OpenAPI仕様に記載**シートで、選択内容を確認します。

| 選択項目 | 内容 |
| --- | --- |
| **リクエスト** | **ワークスペース全体**、または1つのフォルダ。サブフォルダ内のリクエストも含まれます。 |
| **仕様** | **新規仕様**、または追加先のワークスペース内の仕様。すでに仕様に従っているフォルダは、その仕様に追加します。 |
| **タイトル** | 新規仕様のタイトル。最初は、フォルダまたはワークスペースの名前になっています。 |
| **「フォルダ」を仕様にリンク** | デフォルトでオン。フォルダのリクエストが、変換先のオペレーションに従うので、あとで仕様に加えた変更をリクエストに適用できます。 |

</Step>
<Step>

**記載**をクリックします。シートに結果が表示され、**仕様を開く**で結果を開きます。

</Step>
</Steps>

<Shot id="specs-from-responses" alt="Catalogフォルダを記載したあとの「OpenAPI仕様に記載」シート。新しいオペレーション、除外されたリクエストとその理由、「仕様を開く」ボタンが表示されている" />

## 結果 [#what-you-get]

結果には次の項目が一覧表示されます。

| 見出し | 意味 |
| --- | --- |
| **新しいオペレーション** | 仕様になかったオペレーション。`GET /products/{sku}`など。 |
| **レスポンスを追加** | すでにあったオペレーションのうち、`404`など別のレスポンスが記述に加わったもの。 |
| **記載済み** | すでに、応答されたとおりに記述されていたオペレーション。何も変更されません。 |
| **除外** | 記述されなかったリクエストと、それぞれの理由。 |

そのほか、いくつのリクエストがオペレーションに従うようになったか、結果にLintがいくつのエラーを見つけたか（ある場合）も表示されます。

各オペレーションに入る内容は次のとおりです。

- **パス**はOpenAPIの形式になります。変数から来たパスセグメントはパスパラメータになり、送信した値とともに記述されます。URLのサーバ部分はパスから除かれます。
- リクエストが設定する**クエリパラメータとヘッダー**。
- **リクエストボディ**と**レスポンス**。ボディから作成したJSON Schemaと例が付きます。大きな例は省かれてスキーマだけが残り、長い配列は例に数項目だけが残ります。
- オペレーションの概要には**リクエストの名前**、タグには**そのサブフォルダ**が使われます。
- **リクエストの認証**はセキュリティスキームになります。OpenAPIにスキームがない場合（デバイスコードグラントのOAuth 2）は、その旨の注記が付きます。

シークレットはマスクされます。シークレットの変数や、シークレットらしいキー（トークン、パスワード、鍵）の値は、例の中で`••••••`と表示されます。

## すでにある仕様に追加する [#adding-to-a-spec-you-have]

**仕様**で仕様を選択します。Echolotは、足りないものだけを追加します。まだ名前のないオペレーション、レスポンス、スキーマ、セキュリティスキームです。仕様にすでに書かれている内容は、そのまま残ります。
Swagger 2.0の仕様には追加できません。追加できるのはOpenAPI 3のドキュメントだけです。

## 履歴から単一のレスポンスを記述する [#documenting-single-responses-from-history]

[履歴](/docs/workspaces/history)で、レスポンスを得たHTTPのやり取りを右クリックして、<strong>OpenAPI仕様に追加…</strong>を選択します。同じシートが、その1つのレスポンスについて開きます。
エラーのように、一度だけ見たレスポンスを記述するのに便利です。

## 除外されるもの [#what-is-left-out]

- HTTP以外のリクエスト（GraphQL、gRPC、WebSocketなど）：OpenAPIに記述されるのはHTTPリクエストだけです。
- まだレスポンスがないリクエスト：先に送信してください。
- レスポンスを得る前に送信に失敗したリクエスト。
- 独自の仕様に従っているサブフォルダ内のリクエスト。

## 最新に保つ [#keep-it-current]

フォルダが仕様に従うようになったら、仕様が契約になります。仕様ページで編集し、<strong>「フォルダ」の変更を確認…</strong>で、その変更をリクエストに適用します。[仕様に従うリクエスト](/docs/specs#requests-that-follow-the-spec)を参照してください。
仕様のレスポンスを[モック](/docs/mocks)に提供して、フロントエンドがそれに対して作業できるようにすることもできます。

エージェントも、**仕様**ツールセットがオンのときは、`add_to_spec`ツールで同じことができます。[エージェント](/docs/ai/agents)を参照してください。