Echolotレスポンスから作る仕様
送信したリクエストとそのレスポンスから、OpenAPI仕様を書き出します。
仕様より先に、リクエストがあることはよくあります。誰かが読み込んだコレクションや、APIを調べるうちに試した呼び出しなどです。 レスポンスから作る仕様は、それらをOpenAPIドキュメントに変換します。各リクエストは、最後に得たレスポンスをもとに記述されたオペレーションになります。 パスとパラメータ、送信したボディ、そしてレスポンスのボディのJSON Schemaと例が含まれます。すでにある仕様に追加することもでき、その場合は足りないものだけが加わります。
フォルダを記述する
記述したいリクエストを送信して、それぞれにレスポンスがある状態にします。たとえばAlpenglowでは、Catalogフォルダのリクエストを送信します。
リクエストのサイドバーでフォルダを右クリックして、OpenAPI仕様に記述…を選択します。ワークスペース全体を記述するには、仕様のサイドバーで+ › レスポンスから新規仕様…、空の仕様ページでレスポンスから…、またはコマンドパレットでレスポンスから新規仕様…を選択します。
OpenAPI仕様に記載シートで、選択内容を確認します。
| 選択項目 | 内容 |
|---|---|
| リクエスト | ワークスペース全体、または1つのフォルダ。サブフォルダ内のリクエストも含まれます。 |
| 仕様 | 新規仕様、または追加先のワークスペース内の仕様。すでに仕様に従っているフォルダは、その仕様に追加します。 |
| タイトル | 新規仕様のタイトル。最初は、フォルダまたはワークスペースの名前になっています。 |
| 「フォルダ」を仕様にリンク | デフォルトでオン。フォルダのリクエストが、変換先のオペレーションに従うので、あとで仕様に加えた変更をリクエストに適用できます。 |
記載をクリックします。シートに結果が表示され、仕様を開くで結果を開きます。
結果
結果には次の項目が一覧表示されます。
| 見出し | 意味 |
|---|---|
| 新しいオペレーション | 仕様になかったオペレーション。GET /products/{sku}など。 |
| レスポンスを追加 | すでにあったオペレーションのうち、404など別のレスポンスが記述に加わったもの。 |
| 記載済み | すでに、応答されたとおりに記述されていたオペレーション。何も変更されません。 |
| 除外 | 記述されなかったリクエストと、それぞれの理由。 |
そのほか、いくつのリクエストがオペレーションに従うようになったか、結果にLintがいくつのエラーを見つけたか（ある場合）も表示されます。
各オペレーションに入る内容は次のとおりです。
- パスはOpenAPIの形式になります。変数から来たパスセグメントはパスパラメータになり、送信した値とともに記述されます。URLのサーバ部分はパスから除かれます。
- リクエストが設定するクエリパラメータとヘッダー。
- リクエストボディとレスポンス。ボディから作成したJSON Schemaと例が付きます。大きな例は省かれてスキーマだけが残り、長い配列は例に数項目だけが残ります。
- オペレーションの概要にはリクエストの名前、タグにはそのサブフォルダが使われます。
- リクエストの認証はセキュリティスキームになります。OpenAPIにスキームがない場合（デバイスコードグラントのOAuth 2）は、その旨の注記が付きます。
シークレットはマスクされます。シークレットの変数や、シークレットらしいキー（トークン、パスワード、鍵）の値は、例の中で••••••と表示されます。
すでにある仕様に追加する
仕様で仕様を選択します。Echolotは、足りないものだけを追加します。まだ名前のないオペレーション、レスポンス、スキーマ、セキュリティスキームです。仕様にすでに書かれている内容は、そのまま残ります。 Swagger 2.0の仕様には追加できません。追加できるのはOpenAPI 3のドキュメントだけです。
履歴から単一のレスポンスを記述する
履歴で、レスポンスを得たHTTPのやり取りを右クリックして、OpenAPI仕様に追加…を選択します。同じシートが、その1つのレスポンスについて開きます。 エラーのように、一度だけ見たレスポンスを記述するのに便利です。
除外されるもの
- HTTP以外のリクエスト（GraphQL、gRPC、WebSocketなど）：OpenAPIに記述されるのはHTTPリクエストだけです。
- まだレスポンスがないリクエスト：先に送信してください。
- レスポンスを得る前に送信に失敗したリクエスト。
- 独自の仕様に従っているサブフォルダ内のリクエスト。
最新に保つ
フォルダが仕様に従うようになったら、仕様が契約になります。仕様ページで編集し、「フォルダ」の変更を確認…で、その変更をリクエストに適用します。仕様に従うリクエストを参照してください。 仕様のレスポンスをモックに提供して、フロントエンドがそれに対して作業できるようにすることもできます。
エージェントも、仕様ツールセットがオンのときは、add_to_specツールで同じことができます。エージェントを参照してください。