書くなら YAML
長い説明は YAML のブロックテキストのほうが読みやすく、コメントでレビュー担当者向けの注釈も付けられます。
$ref パスやレスポンスコードを壊さずに、API 仕様を JSON と YAML の間で変換します。
出力の各行を既定の書式で表示し、その行が持つ値のパスを横に示します。行をクリックするとパスをコピーできます。
すべてブラウザ内で動作し、データはアップロードされません。スパムやボットを防ぐため、公正利用の制限(入力 1 件あたり 5 MB、変換回数のレート制限)があります。
手作業で変換した仕様が壊れる原因は 2 つあります。YAML のコメントを始めてしまう #、そして整数になってしまうステータスコードです。どちらにも対応しています。
{
"paths": {
"/pets/{id}": {
"get": {
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Pet"
}
}
}
},
"4XX": {
"description": "Client error"
}
}
}
}
}
} paths:
/pets/{id}:
get:
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Pet'
4XX:
description: Client error 引用符なしの手書きに切り替えると、$ref が null になり、ワイルドカードのホストが解析に失敗する様子がわかります。
変換後はリンターを実行して、構文だけでなく仕様そのものをチェックしましょう。ここでは編集に合わせて、ローカルの $ref をすべてチェックします。
# Lint the converted spec (OpenAPI 3.x and Swagger 2.0)
npx @redocly/cli lint openapi.yaml 長い説明は YAML のブロックテキストのほうが読みやすく、コメントでレビュー担当者向けの注釈も付けられます。
コードジェネレーター、ゲートウェイ、SDK は JSON を最も速く読み込むことが多く、多くは /openapi.json で仕様を配信しています。
どちらの形式も同じ API を記述します。どちらの方向にも自由に変換でき、仕様の内容は何も失われません。
JSON と YAML が出会うあらゆる場面のための変換ツール、検証ツール、手順ガイド。
openapi.json を貼り付けるかアップロードし、右側のペインから YAML をコピーするか、openapi.yaml としてダウンロードします。構造、$ref ポインター、例、説明はそのまま保たれます。
はい。コンバーターはドキュメントの構造に対して動作するため、Swagger 2.0、OpenAPI 3.0、OpenAPI 3.1 の仕様はどれも両方向に同じように変換されます。
YAML では、スペースの後の # はコメントの開始です。引用符がないと $ref: 以降がすべてコメントとして扱われ、参照が空になってしまいます。コンバーターは自動で引用符を付けます。
OpenAPI ではレスポンスコードを文字列のキーにする必要があります。引用符のない 200 は YAML では整数です。ほとんどのツールは受け付けますが、厳密なバリデーターは受け付けません。引用符で囲めば、どこでも仕様が有効なまま保たれます。
エディター上部の切り替えで変換方向を YAML → JSON にするか、YAML から JSON への変換ツールを使います。JSON にはその種の参照がないため、YAML のアンカーは展開されます。