OpenAPI・Swagger の JSON から YAML へ

$ref パスやレスポンスコードを壊さずに、API 仕様を JSON と YAML の間で変換します。

出力オプション

JSON入力

空

YAML出力

YAML の出力がここに表示されます

すべてブラウザ内で動作し、データはアップロードされません。スパムやボットを防ぐため、公正利用の制限(入力 1 件あたり 5 MB、変換回数のレート制限)があります。

URL から読み込む

ファイルはブラウザから直接取得されるため、サーバー側でクロスオリジンリクエストが許可されている必要があります。

キーボードショートカット

Ctrl / ⌘ + Enter 今すぐ変換
Ctrl / ⌘ + S 出力をダウンロード
Alt + Shift + C 出力をコピー
Alt + Shift + F 入力の JSON を修復して整形
Alt + Shift + S 変換方向を入れ替え
Alt + Shift + T コード、ツリー、マップ表示を切り替える
Ctrl / ⌘ + Z 元に戻す(整形、修復、クリアも対象)
Esc 全画面表示を終了
エディターの文字サイズ

$ref ポインターとレスポンスコードは有効なまま

手作業で変換した仕様が壊れる原因は 2 つあります。YAML のコメントを始めてしまう #、そして整数になってしまうステータスコードです。どちらにも対応しています。

openapi.json
{
  "paths": {
    "/pets/{id}": {
      "get": {
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Pet"
                }
              }
            }
          },
          "4XX": {
            "description": "Client error"
          }
        }
      }
    }
  }
}
openapi.yaml
paths:
  /pets/{id}:
    get:
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
        4XX:
          description: Client error

引用符なしの手書きに切り替えると、$ref が null になり、ワイルドカードのホストが解析に失敗する様子がわかります。

結果をリントする

変換後はリンターを実行して、構文だけでなく仕様そのものをチェックしましょう。ここでは編集に合わせて、ローカルの $ref をすべてチェックします。

bash
# Lint the converted spec (OpenAPI 3.x and Swagger 2.0)
npx @redocly/cli lint openapi.yaml

API 仕様には JSON と YAML のどちら?

書くなら YAML

長い説明は YAML のブロックテキストのほうが読みやすく、コメントでレビュー担当者向けの注釈も付けられます。

ツールには JSON

コードジェネレーター、ゲートウェイ、SDK は JSON を最も速く読み込むことが多く、多くは /openapi.json で仕様を配信しています。

同じドキュメント

どちらの形式も同じ API を記述します。どちらの方向にも自由に変換でき、仕様の内容は何も失われません。

その他のツール

JSON と YAML が出会うあらゆる場面のための変換ツール、検証ツール、手順ガイド。

よくある質問

OpenAPI の JSON ファイルを YAML に変換するには?

openapi.json を貼り付けるかアップロードし、右側のペインから YAML をコピーするか、openapi.yaml としてダウンロードします。構造、$ref ポインター、例、説明はそのまま保たれます。

OpenAPI 3 だけでなく Swagger 2.0 にも使えますか?

はい。コンバーターはドキュメントの構造に対して動作するため、Swagger 2.0、OpenAPI 3.0、OpenAPI 3.1 の仕様はどれも両方向に同じように変換されます。

$ref: '#/components/...' が引用符で囲まれるのはなぜですか?

YAML では、スペースの後の # はコメントの開始です。引用符がないと $ref: 以降がすべてコメントとして扱われ、参照が空になってしまいます。コンバーターは自動で引用符を付けます。

レスポンスコードが '200' と書かれるのはなぜですか?

OpenAPI ではレスポンスコードを文字列のキーにする必要があります。引用符のない 200 は YAML では整数です。ほとんどのツールは受け付けますが、厳密なバリデーターは受け付けません。引用符で囲めば、どこでも仕様が有効なまま保たれます。

OpenAPI の YAML を JSON に戻すには?

エディター上部の切り替えで変換方向を YAML → JSON にするか、YAML から JSON への変換ツールを使います。JSON にはその種の参照がないため、YAML のアンカーは展開されます。