API仕様書をブラウザだけで作成できる「OpenAPI GUI Studio」を作ってみた！

Mermaid GUI Studioを作ったとき、「クリックしていくだけで図が組み上がる」感覚が想像以上に快適でした。同じ体験をOpenAPI（Web APIの仕様書フォーマット）でも作れないかと思い立ち、OpenAPI GUI Studio という自作ツールを公開しました。

👉 OpenAPI GUI Studioを開く

この記事では、単なる「YAMLを書くのが面倒だからGUIにした」ツールで終わらせないために入れた工夫と、実際の使い方を紹介します。

何を作ったか（What is OpenAPI GUI Studio?）

ひとことで言うと、OpenAPI 3.0/3.1形式のAPI仕様書を、フォームを埋めるだけで組み立てられるブラウザツールです。他の自作ツールと同じく、サーバーとの通信は行わず、ブラウザだけで完結します（「テスト実行」機能で自分が指定したAPIサーバーへ通信する場合を除く）。

画面は3つの列に分かれています。

列	役割
WebAPI設計GUI	プロジェクト設定・サーバー・エンドポイント・パラメータなどをフォームで編集
JSON（OpenAPI仕様）	上記の内容がリアルタイムで反映される、正規のOpenAPI JSON
レンダリングプレビュー	Swagger UI風のドキュメント表示＋その場でテスト実行

GUIを編集すればJSONとプレビューに、JSONを直接編集すればGUIとプレビューに、それぞれ即座に反映されます。「フォームは楽だけど細かい調整がしづらい」「JSONは正確だけど書くのが面倒」という、よくあるジレンマを両取りできる作りにしています。

flowchart LR
  GUI["WebAPI設計GUI<br/>(フォーム編集)"] <--> MODEL["内部データモデル<br/>(正規のOpenAPI構造)"]
  MODEL <--> JSON["JSON表示・編集エリア"]
  MODEL --> PREVIEW["レンダリングプレビュー"]
  MODEL --> YAML["YAML書き出し"]
  MODEL --> POSTMAN["Postmanコレクション書き出し"]
  MODEL --> MD["Markdown/HTML書き出し"]
  PREVIEW -->|テスト実行| API["指定したAPIサーバー"]

こだわったポイント

1. GUIの都合で、OpenAPIとして壊れた出力にしない

内部のデータは最初から正規のOpenAPI構造（parameters[].schema.typeのネスト、requestBody.content、responses.*.contentなど）で保持しています。GUI操作用の補助情報（処理シーケンスやテストケースなど、OpenAPI標準にない項目）は、すべてx-で始まるベンダー拡張フィールド（x-sequence、x-testなど）に閉じ込めています。OpenAPIの仕様上、x-から始まるフィールドはどこに置いても良いことになっているので、「GUIとしての使いやすさ」と「標準準拠のJSON/YAML出力」を両立できます。

2. YAMLパーサーは同梱していない

編集エリアはJSON形式です。世の中にはYAMLパーサーのライブラリがいくつもありますが、外部ライブラリを同梱すると、そのライブラリ自体の脆弱性・ライセンスを継続的に監査する責任が発生します。当サイトの自作ツールは「本体は外部ライブラリに依存しない」方針で作っているため、YAML出力は自己実装した一方向の変換処理（JSON→YAMLのみ、パースはしない）で対応しました。結果として、このツールは外部ライブラリを一切使っていません。

3. パラメータのバリデーションは「本物」と「メモ」を分けている

format（date / email / uuidなど）・minimum / maximum・minLength / maxLength・patternといった制約は、JSON Schema／OpenAPIの標準機能としてそのまま出力します。Swagger UIなど他のツールでもそのまま解釈できる「本物」の制約です。

一方、「パラメータAが未指定ならパラメータBは必須」「開始日は終了日より前」のようなパラメータ同士を参照する条件は、OpenAPIの仕様上そもそも表現する方法がありません（dependentRequiredのようなJSON Schemaの機能はリクエストボディのオブジェクトに対するもので、独立したクエリパラメータには使えない）。これを「対応できません」で済ませず、x-validation-notesという自由記述メモとして保持・表示できるようにしています。ドキュメントとしては十分価値があるので、「標準にない＝作らない」ではなく「メモとして残す」という判断をしました。

4. テストは複数パターン登録できる

1つのエンドポイントに対して、正常系・異常系など複数のテストケースを登録できます。ケースごとに送信パラメータ・期待ステータスコード・期待レスポンスを個別に設定可能です。

パラメータの入力は、表形式のUIとJSON直接編集を切り替えられるようにしました。

| パラメータ名 | 送信 | 値   |
|--------------|------|------|
| petId        | ☑    | abc  |  ← あえて型不一致の値を入れて検証したい、という要望から生まれたUI

チェックを外すとそのパラメータは送信されない扱いになるので、「必須パラメータを欠いたら本当に400が返るか」のような異常系テストも自然に組み立てられます。

5. ブラウザで動かなければPostmanへ

「▶ テスト実行」は指定したサーバーへ実際にfetchを送ります。ただしこれはブラウザの機能である以上、相手のAPIがCORSに対応していない限り、クロスオリジンのリクエストはブロックされます。これは本ツール固有の制限ではなく、Swagger UIの「Try it out」などでも同じ制約です。

そこで、CORSに左右されず確実にテストしたい場合のために「📮 Postman書き出し」を用意しました。Postman Collection Format v2.1形式のJSONを生成し、Postman（ネイティブアプリなのでCORSの影響を受けない）にインポートしてそのまま実行できます。登録したテストケースは1ケース＝1リクエストとして出力され、期待値はpm.testのアサーションに変換されます。

6. ドキュメントとしてもそのまま書き出せる

作った仕様書は「Markdown書き出し」「HTML書き出し」でそのままドキュメント化できます。HTMLはCSSをすべてインライン化した単体ファイルなので、社内Wikiやメールに添付するだけで共有できます。

実際に触ってみる

ツールを開くとサンプル（Swagger Petstoreを模したAPI）が最初から読み込まれています
左のGUIパネルでエンドポイントを選び、パラメータやレスポンス例を編集してみてください。中央のJSONと右のプレビューが即座に更新されます
右のプレビューにある「▶ テスト実行」を押すと、公式のSwagger Petstoreデモサーバーに対して実際にリクエストが飛びます（デモサーバーの状態によっては失敗することもあります）
表示する列は上部のチェックボックスで自由にON/OFFでき、列の境界をドラッグすれば幅も調整できます。狭い画面では上部の△ボタンでツールバーごと折りたためます

まとめ

「Mermaid GUI Studioと同じ気軽さで、OpenAPIも組み立てたい」という思いつきから始めましたが、実際に手を動かしてみると「GUIの都合を優先してOpenAPIとして壊れたJSONを吐いていないか」「本当に検証できることと、メモとして残すだけのことを混同していないか」など、地味だけど大事な論点がいくつも出てきました。そのぶん、単なる入力フォーム以上のものになったと思います。

ぜひ触ってみてください。

👉 OpenAPI GUI Studioを開く

※この記事はAIを用いて作成しています