OpenAPI / Swagger Formatter
Format and validate OpenAPI / Swagger specs (JSON or YAML) and count paths and operations.
これはローカルツールです。すべてブラウザ内で動作します。貼り付けた OpenAPI または Swagger の仕様はデバイスから離れることはなく、ArrayKit やいかなるサーバーにも何もアップロードされません。
YAML と JSON の間で変換する
OpenAPI / Swagger Formatter について
ArrayKit の OpenAPI フォーマッターは、OpenAPI と Swagger の仕様を JSON または YAML のいずれかで、すべてブラウザ内で整形・検証します。仕様を貼り付けると、ドキュメントを解析し、検出されたバージョン（OpenAPI 3.x または Swagger 2.0）、API のタイトル、定義されているパスとオペレーションの数を報告し、クリーンで一貫したインデントの JSON または YAML を再出力します。手編集したコントラクトを素早く整えたい、JSON と YAML の間で変換したい、コミットや Swagger UI・コードジェネレーター・ゲートウェイへの投入の前に仕様を検証したいバックエンド・API 開発者、テクニカルライター、プラットフォームチームのために作られています。リクエストの構築と解析はローカルで行われるため、内部または未公開の API 定義をサーバーに送らずに整形できます。不正な YAML を検出し、オペレーション数を確認し、リポジトリ全体で整形を統一するのに使えます。
機能
- JSON と YAML の両方の入力を受け付ける — JSON は有効な YAML なのでどちらも解析できる
- 仕様のバージョンを検出してラベル付け：OpenAPI 3.x または Swagger 2.0
- API のタイトルに加え、パスとオペレーションのライブカウントを報告
- 8 つの HTTP オペレーション（get、put、post、delete、options、head、patch、trace）を数える
- 出力を整形済み JSON と 2 スペースの YAML の間で切り替え
- ドキュメントが不正な場合、根底にあるメッセージとともに解析エラーを表示
- openapi や swagger フィールドがない場合に警告し、未知の仕様を目立たせる
- 整形した結果を openapi.json または openapi.yaml としてダウンロード
OpenAPI / Swagger Formatter の使い方
- OpenAPI または Swagger の仕様（JSON または YAML）を入力パネルに貼り付ける
- ツールバーの JSON / YAML トグルで出力形式を選ぶ
- 概要バナーでバージョン、タイトル、パス数、オペレーション数を読む
- 整形した仕様をコピーするか、openapi.json または openapi.yaml としてダウンロードする
例
入力
openapi: 3.0.3
info: { title: Example API, version: 1.0.0 }
paths:
/users:
get: { summary: List users, responses: { '200': { description: OK } } }
post: { summary: Create user, responses: { '201': { description: Created } } }
出力
openapi: 3.0.3
info:
title: Example API
version: 1.0.0
paths:
/users:
get:
summary: List users
responses:
'200':
description: OK
post:
summary: Create user
responses:
'201':
description: Created
最小限の OpenAPI 3.0 仕様 — フォーマッターは「OpenAPI 3.0.3 · Example API · 1 path · 2 operations」と報告します。
よくあるエラーとトラブルシューティング
- 概要に「Unknown — no openapi/swagger field」と表示される。 — トップレベルに openapi: 3.x.x（または swagger: '2.0'）フィールドを追加してください。これがないと、ドキュメントは整形できてもバージョンを検出できません。
- 多くの場合、不正なインデントやタブ文字に関する YAML 解析エラーが出る。 — YAML はインデントに敏感でタブを禁止しています。タブをスペースに置き換え、キーを一貫して揃えてから貼り直してください。
- オペレーション数が予想より少なく見える。 — 標準の 8 つの HTTP メソッドのみが数えられます。x-amazon-apigateway-integration などのベンダー拡張や parameters/servers のエントリはオペレーションではありません。
- 貼り付け後に「The document is empty or not an object」と表示される。 — 入力がスカラーまたは null として解析されました。単一の文字列や部分的な断片ではなく、仕様オブジェクト全体を貼り付けたか確認してください。
よくある質問
- OpenAPI／Swagger フォーマッターとは何ですか？
- OpenAPI 3.x または Swagger 2.0 の API 仕様を解析し、クリーンで一貫したインデントの JSON または YAML として再出力するツールです。同時にバージョンとパス・オペレーションの数を報告するので、仕様を素早く確認・統一できます。
- JSON と YAML の両方の仕様をサポートしますか？
- はい。JSON 自体が有効な YAML なので、どちらの形式も貼り付けられます。JSON / YAML トグルで整形出力の形式を選べ、これにより仕様を一方の形式から他方へ変換することもできます。
- OpenAPI スキーマに対して仕様を完全に検証しますか？
- 整形された JSON または YAML として解析できることを検証し、バージョン、タイトル、パス、オペレーションを検出します。すべてのフィールドの完全な JSON Schema 検証は行わないため、オペレーション内部の必須プロパティ欠落などは指摘しません。
- どのバージョンを認識しますか？
- openapi フィールドで OpenAPI 3.x を、swagger フィールドで Swagger 2.0 をラベル付けします。これらのフィールドがないドキュメントは整形されますが、未知のバージョンとして表示されます。
- 私の API 仕様はどこかにアップロードされますか？
- いいえ。解析、検証、整形はすべてブラウザ内で行われます。貼り付けた仕様はデバイスから離れることはなく、ArrayKit には何もアップロードされないため、内部または未公開の API コントラクトはプライベートに保たれます。
- 整形した結果をダウンロードできますか？
- はい。整形した仕様は、選択した出力形式に応じて openapi.json または openapi.yaml としてコピーまたはダウンロードできます。
関連ツール
すべての ArrayKit ツール