仕様エディタを使って仕様を作成する

仕様エディタを使用すると、コードを記述することなく、OpenAPI 仕様を作成して検証できます。

仕様エディタにアクセスする

以降のセクションの説明に従って、仕様エディタで OpenAPI 仕様を開きます。

次の図は、仕様エディタで開いた Petstore API の仕様を示しています。

前の図でハイライト表示されているように、仕様エディタでは次の操作を行うことができます。

  • OpenAPI 仕様を作成し、JSON または YAML 形式を使って API をモデル化します(左側のペイン)。
  • 右ペインで、自動生成された API ドキュメントを表示します。
  • OpenAPI 仕様標準に照らして、入力した仕様を検証します。
  • OpenAPI 仕様を保存するか、仕様を閉じて編集をキャンセルします。

便利な JSON と YAML を活用する

JSON(JavaScript Object Notation)は、単純なデータ構造と連想配列を表すために使用される軽量のデータ交換形式です。詳細については、https://www.json.org をご覧ください。

YAML(YAML Ain't Markup Language)は、リスト、連想配列、スカラーなどのデータ構造にマップ可能な構文を提供するデータシリアル化/表現標準です。詳細については、https://yaml.org をご覧ください。

JSON と YAML はどちらもマシン可読ですが、人間にとっても読みやすく理解しやすいものです。次の図は、JSON と YAML で記述された、同じ OpenAPI 仕様からの 2 つの短い抜粋を比較しています。

JSON と YAML の比較

仕様を検証する

仕様エディタは、OpenAPI 仕様を OpenAPI 仕様標準に照らして検証します。入力中に OpenAPI 仕様にエラーが存在するようになると、仕様エディタの右ペイン上部に [Error] ダイアログが表示され、エラーとそれに関連する行番号の詳細情報が提供されるのでて、簡単に修正できます。

エラー

仕様を保存する

OpenAPI 仕様を保存するには、上部のナビゲーション バーで [Save] をクリックします。

仕様を初めて保存するときには、ファイル名を入力するように求められます。ファイル名を指定しない場合、デフォルトで Untitled に設定されます。後で、その名前を変更できます。

仕様を閉じる

編集内容を保存せずに OpenAPI 仕様を閉じるには、上部のナビゲーション バーで [Cancel] をクリックします。これにより仕様リストに戻ります。