仕様

仕様ページは、APIの契約を設計して保管する場所です。OpenAPIドキュメント（OpenAPI 3.0と3.1、Swagger 2.0）とgRPCサービスの.protoファイルを扱います。 Echolotは編集中の仕様をチェックし、仕様と同期したままのリクエストに変換し、APIができる前にモックとして提供します。

サイドバーのモジュール切り替えで仕様を選ぶか、⌘3で開きます。

ワークスペースの仕様Copy Anchor Link

仕様はワークスペースのspecsフォルダ内のファイルなので、ほかのものと一緒にGitに入ります。Alpenglowの例には3つあります。alpenglow.yaml（ショップのOpenAPIドキュメント）、shop.graphql、inventory.protoです。 仕様ページでは、OpenAPIドキュメントが仕様の下に、.protoファイルがProtoファイルの下に一覧表示されます。フォルダ内のGraphQLスキーマはGraphQLリクエストが使うもので、ここには表示されません。

サイドバーの仕様ヘッダーの+で追加します。

ファイル › 読み込む…でOpenAPIドキュメントを読み込むのは別の操作です。これはドキュメントからリクエストを作成するもので、編集する仕様を作るものではありません。

仕様を右クリックすると、リクエストを生成、Finderに表示、書き出す（YAMLとして…またはJSONとして…）、削除…を選べます。 削除する前に確認が表示され、ファイルはゴミ箱に入ります。参照しているファイルとその仕様のモックは残ります。

アウトラインCopy Anchor Link

仕様をクリックして開きます。リストの下に、サイドバーがその仕様のアウトラインを表示します。

• 概要：タイトル、バージョン、説明。
• エンドポイント：すべてのオペレーションとそのメソッドおよびパス。非推奨のものには取り消し線が付きます。ポインタを置くと概要が表示されます。
• スキーマ：再利用可能なスキーマ。
• ファイル：仕様がほかのファイルを参照している場合（複数のファイルに分割した仕様を参照）。

項目をクリックして開きます。ビジュアルエディタではそのカードが開いて表示位置までスクロールし、コードではエディタがその行に移動します。

ビジュアルとコードCopy Anchor Link

ページヘッダーのエディタスイッチで、開いている仕様の表示方法を選びます。

• ビジュアル：概要、サーバ、エンドポイント、スキーマのカード。フィールドとメニューで編集します。
• コード：YAMLまたはJSONのドキュメント。行番号付き。

どちらも同じテキストを編集し、Echolotは変更のたびに少し待ってから保存します。どちらについても仕様を編集するで説明しています。

問題Copy Anchor Link

Echolotは編集中の仕様をLintします。エディタの上のバーには、問題なし、またはエラーと警告の数が表示されます。エラーがある場合は、サイドバーの開いている仕様の横にも赤い数が表示されます。

クリックすると一覧が表示されます。エラーが先で、続いて警告とヒントが、それぞれの行とともに並びます。項目を選ぶと、その行に移動します。 一覧が空の場合は、ドキュメントがOpenAPI仕様に従っていて、すべての参照が解決されていることが示されます。

Lintは次のようなことを調べます。

• Echolotが読めるopenapiバージョン、タイトルとバージョンのあるinfo、/で始まるパス。
• パスにありrequired: trueが指定されているパスパラメータ、2回定義されていないパラメータ。
• すべてのレスポンスの説明、1回だけ使われているオペレーションID。
• 先頭で宣言されたタグ、定義されたセキュリティスキーム、itemsのある配列、値のある列挙型。
• 何かを指している参照（このファイル内、またはspecs内の別のファイル）。
• serversがない場合：仕様から作成するリクエストは{{baseUrl}}で始まり、その値は自分で設定します。

コマンドラインツールはCIで同じLintを実行できます。echolot specを参照してください。

複数のファイルに分割した仕様Copy Anchor Link

仕様は、$ref: schemas/pet.yaml#/Petのように$refで、ほかのファイルの一部を取り込めます。ファイルはワークスペースのspecsフォルダ内にある必要があります。 サイドバーのファイルにそれらが一覧表示され、クリックするとコードで開きます。コードエディタでは、$refにポインタを置くと参照先が表示され、⌘クリックすると、このファイルまたは別のファイル内のその場所に移動します。

Echolotは、Lint、リクエストの生成、モックなど、仕様を使うあらゆる場面で、これらの部分をまとめて読み取ります。仕様を書き出すと、参照しているファイルは、保存する1つのファイルに書き込まれます。

書き出すCopy Anchor Link

エディタの上のバーの書き出す（YAMLとして書き出す…またはJSONとして書き出す…）は、仕様を、参照しているファイルを書き込んだ1つのファイルとして、ワークスペースの外に保存します。 保存されていない編集は先に保存されるため、書き出されるのはエディタに表示されている内容です。

仕様に従うリクエストCopy Anchor Link

エディタの上のバーのリクエストを生成は、仕様の名前を付けたフォルダを作成し、各エンドポイントのリクエストを入れて、最初のリクエストを開きます。 このフォルダは仕様に従います。仕様が変更されたら、リクエストで編集した内容を失わずに、その変更をリクエストに適用できます。

フォルダが仕様に従うようになると、ボタンはリクエストに変わります。このメニューには、仕様に従う各フォルダの「フォルダ」の変更を確認…と、別のフォルダを生成があります。 確認するとOpenAPI同期が開き、仕様で新規、仕様で変更、仕様から削除が一覧表示されます。 適用したい変更にチェックを付けて、1件の変更を適用（3件の変更を適用など）をクリックします。 あなたの編集は必ず残ります。あなたと仕様が同じものを変更した場合は、あなたの編集が残ります。 オペレーションがなくなった場合、そのリクエストはゴミ箱に入ります。ただし、編集したリクエストは残り、仕様に従わなくなります。 リンクを解除は、フォルダが仕様に従わないようにし、リクエストはそのまま残します。

フォルダは、ワークスペースの外にある仕様（ファイルまたはURL）に従うこともできます。リクエストのサイドバーでフォルダを右クリックして、OpenAPI仕様にリンク…を選択します。 コマンドラインツールでは、echolot spec checkとecholot spec applyで変更を確認して適用します。