# 仕様を編集する (/ja/docs/specs/editing) 仕様の編集方法は2つあり、ページヘッダーの**エディタ**でいつでも切り替えられます。カードとフィールドの**ビジュアル**と、YAMLまたはJSONそのものの**コード**です。 どちらも同じテキストを変更します。Echolotが保持するのはそのテキストです。ビジュアルでの編集は、編集した部分の行だけを変更するため、コメント、順序、書式は保たれ、Gitの差分には変更内容だけが表示されます。 仕様を始めるには、サイドバーの仕様ヘッダーで+ › 新規仕様を選択します。EcholotはOpenAPI 3.1ドキュメントを`New API`というタイトルで`specs`フォルダに作成し、ビジュアルエディタで開きます。 ## ビジュアルエディタ [#the-visual-editor] ビジュアルエディタのフィールドは、編集を終えたときにドキュメントを変更します。↩を押すか、別のフィールドに移動します。 説明のフィールドはMarkdownを使え、↩で改行します。横のボタンで、説明が実際に表示される形を確認できます。 ページには次のカードがあります。 | カード | 編集する内容 | | --- | --- | | **概要** | APIの**タイトル**、**バージョン**、**説明**。 | | サーバ | サーバのURLと説明。サーバを追加で追加し、−で削除します。サーバがない場合、仕様から作成するリクエストは`{{baseUrl}}`で始まり、その値は自分で設定します。 | | **連絡先とライセンス** | **表示**で、連絡先の名前、メールアドレス、URL、ライセンスとそのURL、利用規約が開きます。 | | **エンドポイント** | すべてのオペレーション。**グループ化**で**パス**または**タグ**別に一覧表示します（タグのないものは**タグなし**の下）。クリックして開きます。 | | **スキーマ** | 再利用可能なスキーマ。ボディやレスポンスから名前で参照できます。クリックして開きます。 | ### エンドポイントを追加する [#adding-an-endpoint] **エンドポイント**カードの**エンドポイントを追加**をクリックします。**新規エンドポイント**シートでメソッドを選び、パス（`/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つのボタンがあります。**リクエストを開く**（このオペレーションに従うリクエストがある場合）、**コードで表示**、**エンドポイントを削除**です。 ### スキーマを追加する [#adding-a-schema] **スキーマ**カードの**スキーマを追加**をクリックし、`Product`のような名前を付けて、**追加**をクリックします。 開いたスキーマには、**名前**、**説明**、**プロパティ**があります。各プロパティには、名前、型、**必須**、説明があります。**プロパティを追加**で追加します。 スキーマには、使われている場所が表示されます（**3個所で使用**、または**未使用**）。名前を変更すると、すべての参照が変更されます。 スキーマが使われている場合、**スキーマを削除**は先に確認します。それらの参照が何も指さなくなるためです。単純なオブジェクトではないスキーマは、コードで記述して編集します。**コードで表示**で移動できます。 ### Swagger 2.0 [#swagger-20] Swagger 2.0のドキュメントは、ビジュアルエディタで開いて読めますが、編集は**コード**で行います。EcholotはOpenAPI 3を設計します。 ## コードエディタ [#the-code-editor] **エディタ**を**コード**に切り替えると、YAMLまたはJSONを直接編集できます。Lintは入力中、短い間を置いて実行され、エラーと警告はその行に下線で示され、ポインタを置くとメッセージが表示されます。 `$ref`にポインタを置くと参照先が表示され、⌘クリックするとそこに移動します。別のファイルへの参照は、そのファイルを開きます。仕様が参照しているファイルは、常にコードで開きます。 テキストを解析できない場合、ビジュアルエディタにはビジュアルエディタには、解析できるドキュメントが必要です。と、行とエラーが表示されます。コードで修正で、その行に移動します。 ## 保存 [#saving] 手動で保存する必要はありません。Echolotは、変更のたびに少し待ってから仕様を書き込み、別の仕様に切り替えたとき、ページを離れたとき、ウインドウを閉じたときにも書き込みます。動作中のその仕様のモックにも変更が反映されます。 ファイルを書き込めない場合（たとえば読み取り専用になった場合）は、Echolotが**仕様を保存できませんでした**と表示し、編集内容をエディタに保持します。 | ボタン | 動作 | | --- | --- | | **再試行** | もう一度ファイルの書き込みを試みます。 | | **コピーを保存…** | 編集内容を、選択したファイルに書き込みます。 | | **変更内容を破棄** | ディスク上のファイルの状態に戻します。 | | **編集を続ける** | メッセージを閉じます。編集内容は残り、保存されるまでページはこの仕様のままです。 | ## 取り消す [#undo] **編集 › 取り消す**（⌘Z）はどちらのエディタでも編集を取り消し、**編集 › やり直す**（⇧⌘Z）は元に戻します。 ビジュアルでの編集は1回ごとに1ステップです。入力は、手を止めるまでが1ステップです。取り消しは、変更した仕様に属します。別のファイルを開くと、前のファイルには及びません。 ## エージェントと使う [#with-an-agent] 外部の[エージェント](/docs/ai/agents)は、**設定 › エージェント**でそのエージェントの**仕様**ツールセットをオンにすると、ワークスペースの仕様を読み取り、書き込み、Lintできます。