# 仕様 (/ja/docs/specs)

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

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

<Shot id="specs-page" alt="ビジュアルエディタでalpenglow.yamlを開いた仕様ページ。サイドバーに仕様とエンドポイント、スキーマのアウトラインが並び、ページに概要、サーバ、エンドポイントのカードが表示されている" />

## ワークスペースの仕様 [#specs-in-the-workspace]

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

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

| 項目 | 内容 |
| --- | --- |
| **新規仕様** | `New API`というタイトルのOpenAPI 3.1ドキュメントを作成し、ビジュアルエディタで開きます。 |
| **レスポンスから新規仕様…** | 送信したリクエストとそのレスポンスから仕様を書き出します。[レスポンスから作る仕様](/docs/specs/specs-from-traffic)を参照してください。 |
| **仕様ファイルを追加…** | Macから、OpenAPIまたはSwaggerのドキュメント（YAMLまたはJSON）を`specs`フォルダにコピーします。 |
| **新規Protoファイル** | 小さなサンプルサービスから`.proto`ファイルを作成します。[.protoファイル](/docs/specs/proto-files)を参照してください。 |
| **Protoファイルを追加…** | `.proto`ファイルを`specs`フォルダにコピーします。 |

<strong>ファイル › 読み込む…</strong>でOpenAPIドキュメントを[読み込む](/docs/get-started/importing)のは別の操作です。これはドキュメントからリクエストを作成するもので、編集する仕様を作るものではありません。

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

## アウトライン [#the-outline]

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

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

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

## ビジュアルとコード [#visual-and-code]

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

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

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

## 問題 [#problems]

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

<Shot id="specs-problems" alt="仕様の上に表示された問題のポップオーバー。エラーと警告が、それぞれメッセージと行番号とともに一覧表示されている" />

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

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

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

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

## 複数のファイルに分割した仕様 [#specs-split-across-files]

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

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

## 書き出す [#exporting]

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

## 仕様に従うリクエスト [#requests-that-follow-the-spec]

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

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

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