⚡

JSONからOpenAPI (Swagger) 仕様書を秒速で生成するツールを作った話

に公開
API
JSON
Swagger
OpenAPI
DevTools
idea

はじめに

API開発において、OpenAPI (Swagger) の仕様書を書くのは避けて通れない道ですが、正直言って面倒くさいですよね。

特に、すでに実装済みのAPIや、外部APIのレスポンス例（JSON）がある場合、「このJSONの構造をそのままYAMLのスキーマ定義に変換したい」と思うことが多々あります。
手書きで type: object や properties をネストしていくのは、時間もかかるしインデントのミスも起きがちです。

そこで、JSONを貼り付けるだけで、瞬時にOpenAPIのSchemaオブジェクト（YAML）に変換するツールを作りました。

https://devtoolkits.app/ja/tools/json-to-openapi

どんなツール？

「JSON to OpenAPI Converter」は、ブラウザ上で動作する開発者向けツールです。
左側のエリアにJSONを貼り付けると、右側にOpenAPI 3.0 / 3.1 準拠のYAMLスキーマがリアルタイムで生成されます。

特徴

  • ⚡ リアルタイム変換: 入力と同時に変換されるので、待ち時間がありません。
  • 📝 正確な型推論: 文字列 (string)、数値 (number/integer)、真偽値 (boolean)、配列 (array)、オブジェクト (object) を自動で判別します。
  • 🌳 深いネストも対応: 複雑なJSON構造も再帰的に解析し、正しいインデントで出力します。
  • 📋 ワンクリックコピー: 生成されたYAMLはボタン一つでクリップボードにコピーできます。

使い方

使い方は非常にシンプルです。

  1. JSON to OpenAPI Converter にアクセスします。
  2. 左側のテキストエリアに、変換したいJSONをペーストします。
  3. 右側に生成されたYAMLが表示されるので、コピーしてご自身のOpenAPI定義ファイル（openapi.yaml など）に貼り付けてください。

変換例

例えば、以下のようなJSONを入力すると：

{
  "id": 123,
  "name": "User Name",
  "tags": ["admin", "editor"],
  "profile": {
    "active": true
  }
}

以下のようなYAMLが生成されます：

type: object
properties:
  id:
    type: integer
  name:
    type: string
  tags:
    type: array
    items:
      type: string
  profile:
    type: object
    properties:
      active:
        type: boolean

おわりに

API仕様書の作成は、「本質的な設計」に時間を使うべきであり、「YAMLの記述」に時間を奪われるべきではありません。
このツールが、日々の開発業務の効率化に少しでも役立てば嬉しいです。

他にも DevToolkits では、エンジニアの「ちょっとした作業」を楽にするツールを公開しています。ぜひチェックしてみてください。

Discussion