仕様エディタを使用すると、コードを記述することなく、OpenAPI 仕様を作成して検証できます。
仕様エディタにアクセスする
以降のセクションの説明に従って、仕様エディタで OpenAPI 仕様を開きます。
次の図は、仕様エディタで開いた Petstore API の仕様を示しています。
前の図でハイライト表示されているように、仕様エディタでは次の操作を行うことができます。
- OpenAPI 仕様を作成し、JSON または YAML 形式を使って API をモデル化します（左側のペイン）。
- 右ペインで、自動生成された API ドキュメントを表示します。
- OpenAPI 仕様標準に照らして、入力した仕様を検証します。
- OpenAPI 仕様を保存するか、仕様を閉じて編集をキャンセルします。
便利な JSON と YAML を活用する
JSON（JavaScript Object Notation）は、単純なデータ構造と連想配列を表すために使用される軽量のデータ交換形式です。詳細については、https://www.json.org をご覧ください。
YAML（YAML Ai n't Markup Language）は、リスト、連想配列、スカラーなどのデータ構造にマップ可能な構文を提供する、データのシリアル化 / 表現の標準です。詳細については、https://yaml.org をご覧ください。
JSON と YAML はどちらもマシン可読ですが、人間にとっても読みやすく理解しやすいものです。次の図は、JSON と YAML で記述された、同じ OpenAPI 仕様からの 2 つの短い抜粋を比較しています。
仕様を検証する
仕様エディタは、OpenAPI 仕様を OpenAPI 仕様標準に照らして検証します。入力中に OpenAPI 仕様にエラーが存在するようになると、仕様エディタの右ペイン上部に [Error] ダイアログが表示され、エラーとそれに関連する行番号の詳細情報が提供されるので、簡単に修正できます。
仕様を保存する
OpenAPI 仕様を保存するには、上部のナビゲーション バーで [Save] をクリックします。
仕様を初めて保存するときには、ファイル名を入力するように求められます。ファイル名を指定しない場合、デフォルトで Untitled に設定されます。後で、その名前を変更できます。
仕様を閉じる
編集内容を保存せずに OpenAPI 仕様を閉じるには、上部のナビゲーション バーで [Cancel] をクリックします。これにより仕様リストに戻ります。