Echolot仕様を編集する
OpenAPIドキュメントを、ビジュアルエディタまたはYAMLで設計します。入力中のLint、保存、取り消しに対応しています。
仕様の編集方法は2つあり、ページヘッダーのエディタでいつでも切り替えられます。カードとフィールドのビジュアルと、YAMLまたはJSONそのもののコードです。 どちらも同じテキストを変更します。Echolotが保持するのはそのテキストです。ビジュアルでの編集は、編集した部分の行だけを変更するため、コメント、順序、書式は保たれ、Gitの差分には変更内容だけが表示されます。
仕様を始めるには、サイドバーの仕様ヘッダーで+ › 新規仕様を選択します。EcholotはOpenAPI 3.1ドキュメントをNew APIというタイトルでspecsフォルダに作成し、ビジュアルエディタで開きます。
ビジュアルエディタ
ビジュアルエディタのフィールドは、編集を終えたときにドキュメントを変更します。↩を押すか、別のフィールドに移動します。 説明のフィールドはMarkdownを使え、↩で改行します。横のボタンで、説明が実際に表示される形を確認できます。
ページには次のカードがあります。
| カード | 編集する内容 |
|---|---|
| 概要 | APIのタイトル、バージョン、説明。 |
| サーバ | サーバのURLと説明。サーバを追加で追加し、−で削除します。サーバがない場合、仕様から作成するリクエストは{{baseUrl}}で始まり、その値は自分で設定します。 |
| 連絡先とライセンス | 表示で、連絡先の名前、メールアドレス、URL、ライセンスとそのURL、利用規約が開きます。 |
| エンドポイント | すべてのオペレーション。グループ化でパスまたはタグ別に一覧表示します（タグのないものはタグなしの下）。クリックして開きます。 |
| スキーマ | 再利用可能なスキーマ。ボディやレスポンスから名前で参照できます。クリックして開きます。 |
エンドポイントを追加する
エンドポイントカードのエンドポイントを追加をクリックします。新規エンドポイントシートでメソッドを選び、パス（/products/{sku}など）を入力し、必要なら概要とタグも入力して、エンドポイントを追加をクリックします。
Echolotがパスのパラメータを定義し、出発点としてボディと成功レスポンスを追加します。すでにあるメソッドとパスの組み合わせは受け付けられません。
開いたエンドポイントには次の部分があります。
| 部分 | 編集する内容 |
|---|---|
| エンドポイント | メソッドとパス。変更すると、オペレーションが移動します。 |
| 概要、説明 | List productsのような短い名前と、その動作、必要なもの、返すもの。 |
| オペレーションID、タグ | コードジェネレータが使うID、およびカンマで区切ったタグ。 |
| 非推奨 | オペレーションを非推奨にします。 |
| パラメータ | 各パラメータの名前、場所（場所：path、query、header、cookie）、型、必須、説明。パラメータを追加で追加します。パスに定義されていないパラメータがある場合は、{sku}を追加のようなボタンで定義できます。パス全体と表示されたパラメータは、そのパスのすべてのメソッドに定義されます。 |
| リクエストボディ | ボディを追加でJSONボディを追加します。メディアタイプごとにスキーマがあり、ボディは必須にできます。ボディを削除で取り除きます。 |
| レスポンス | ステータスコードごとに1行。説明と、ボディを追加後はメディアタイプとスキーマも持ちます。レスポンスを追加は、まだ使われていない次の一般的なコード（200、201、204、400、401、403、404、409、422、500、defaultの順）を追加します。コードを編集して変更できます。オペレーションには、少なくとも1つのレスポンスが必要です。 |
パラメータ、ボディ、プロパティの型はメニューで選びます。再利用可能なスキーマ、string、integer、number、boolean、object、それらの配列、またはなしです。
メニューで表せないスキーマは書かれたとおりに表示され、ほかのものを選ぶまで保持されます。
開いたエンドポイントの下部には、Lintがそこで見つけた最初の問題（ポインタを置くとすべて表示されます）と、3つのボタンがあります。リクエストを開く（このオペレーションに従うリクエストがある場合）、コードで表示、エンドポイントを削除です。
スキーマを追加する
スキーマカードのスキーマを追加をクリックし、Productのような名前を付けて、追加をクリックします。
開いたスキーマには、名前、説明、プロパティがあります。各プロパティには、名前、型、必須、説明があります。プロパティを追加で追加します。
スキーマには、使われている場所が表示されます（3個所で使用、または未使用）。名前を変更すると、すべての参照が変更されます。 スキーマが使われている場合、スキーマを削除は先に確認します。それらの参照が何も指さなくなるためです。単純なオブジェクトではないスキーマは、コードで記述して編集します。コードで表示で移動できます。
Swagger 2.0
Swagger 2.0のドキュメントは、ビジュアルエディタで開いて読めますが、編集はコードで行います。EcholotはOpenAPI 3を設計します。
コードエディタ
エディタをコードに切り替えると、YAMLまたはJSONを直接編集できます。Lintは入力中、短い間を置いて実行され、エラーと警告はその行に下線で示され、ポインタを置くとメッセージが表示されます。
$refにポインタを置くと参照先が表示され、⌘クリックするとそこに移動します。別のファイルへの参照は、そのファイルを開きます。仕様が参照しているファイルは、常にコードで開きます。
テキストを解析できない場合、ビジュアルエディタにはビジュアルエディタには、解析できるドキュメントが必要です。と、行とエラーが表示されます。コードで修正で、その行に移動します。
保存
手動で保存する必要はありません。Echolotは、変更のたびに少し待ってから仕様を書き込み、別の仕様に切り替えたとき、ページを離れたとき、ウインドウを閉じたときにも書き込みます。動作中のその仕様のモックにも変更が反映されます。
ファイルを書き込めない場合（たとえば読み取り専用になった場合）は、Echolotが仕様を保存できませんでしたと表示し、編集内容をエディタに保持します。
| ボタン | 動作 |
|---|---|
| 再試行 | もう一度ファイルの書き込みを試みます。 |
| コピーを保存… | 編集内容を、選択したファイルに書き込みます。 |
| 変更内容を破棄 | ディスク上のファイルの状態に戻します。 |
| 編集を続ける | メッセージを閉じます。編集内容は残り、保存されるまでページはこの仕様のままです。 |
取り消す
編集 › 取り消す（⌘Z）はどちらのエディタでも編集を取り消し、編集 › やり直す（⇧⌘Z）は元に戻します。 ビジュアルでの編集は1回ごとに1ステップです。入力は、手を止めるまでが1ステップです。取り消しは、変更した仕様に属します。別のファイルを開くと、前のファイルには及びません。
エージェントと使う
外部のエージェントは、設定 › エージェントでそのエージェントの仕様ツールセットをオンにすると、ワークスペースの仕様を読み取り、書き込み、Lintできます。