OpenAPI仕様書のイメージ

OpenAPI Specification (OAS) とは？

OpenAPI Specification (OAS) は、RESTful APIのインターフェースを記述するための、特定の言語に依存しない標準的な仕様です。以前は「Swagger」と呼ばれていましたが、現在はコミュニティ主導のオープンプロジェクトとして管理されています。

YAMLまたはJSON形式で記述され、以下のような開発フローの自動化に不可欠な存在となっています：

  • APIドキュメントの自動生成: Swagger UIなどによるインタラクティブなドキュメンテーション。
  • クライアントコードの生成: 様々な言語のSDK（ライブラリ）を自動出力。
  • モックサーバーの構築: フロントエンド開発を先行させるためのダミーサーバー。
  • 品質管理: リクエスト・レスポンスのスキーマ検証。

スキーマ定義における「ネスト」の課題

API仕様書を作成する際、最も手間がかかるのがリクエストボディやレスポンスボディの「Schema」定義です。
特に、階層が深い（ネストされた）オブジェクトや、多数のプロパティを持つJSONをOpenAPIの構造（type, properties, required, itemsなど）に合わせて手書きするのは、時間がかかるだけでなく入力ミスの原因にもなります。

JSONからの効率的な自動生成

既に動作しているAPIがある場合、あるいはサンプルのレスポンスJSONが手元にある場合は、それを元にスキーマを自動生成するのが最も効率的です。

  1. APIを実行して、実際のJSONデータを取得します。
  2. JSON→OpenAPI生成ツール にそのJSONを貼り付けます。
  3. 数秒で components/schemas 形式の定義が出力されます。
  4. 生成された定義を、あなたの openapi.yaml などの定義ファイルへ統合します。

入力するJSONの例

たとえばユーザー情報を返すAPIなら、次のようなレスポンスJSONをそのまま使えます。

{
  "id": 123,
  "name": "Yamada Taro",
  "email": "taro@example.com",
  "roles": ["admin", "editor"],
  "profile": {
    "createdAt": "2026-01-15T12:00:00Z",
    "isActive": true
  }
}

このJSONから、id は integer、name や email は string、roles は array、profile はネストした object として推論できます。
手書きでは抜けやすい required や items の定義も、自動生成を起点にすれば確認しやすくなります。

生成後に必ず確認したい項目

JSONから作ったOpenAPIスキーマは、完成品ではなく「精度の高い下書き」と考えるのが安全です。
次の点を確認すると、実運用に使いやすい仕様書になります。

  • 実際には省略される可能性がある項目を required から外す
  • ID、金額、件数などの数値型が integer と number のどちらか確認する
  • 日付文字列に format: date-time や format: date が付いているか確認する
  • 配列が空のサンプルだけになっていないか確認する
  • description と example を追加して、利用者が意味を理解できるようにする

とくにサンプルJSONが1件だけの場合、そのデータに含まれている項目がすべて必須扱いになりがちです。
APIの仕様として任意の項目があるなら、生成後に調整しましょう。

当サイトのツールの特徴

DevToolKitsの生成ツールは、最新の OpenAPI 3.1.0 基準で動作します。

  • 型推論: 数値、文字列、真偽値、オブジェクト、配列を正確に判別します。
  • 必須項目の抽出: JSONに含まれるプロパティを自動的に required 項目としてリストアップします（必要に応じて後から調整可能です）。
  • 型の統合 (oneOf): 配列内に異なる型のデータが混在している場合、oneOf を用いて複数の型を網羅的に表現します。
  • 日付形式の検知: 2024-01-15T12:00:00Z のような文字列を検知し、format: date-time を自動付与します。
  • OpenAPI 3.1準拠: nullable: true の代わりに、最新仕様である type: "null" などの表現にも最適化されています。

よくある質問

Swaggerにも使えますか？

はい。OpenAPIは以前Swaggerと呼ばれていた流れがあり、現在でも「Swaggerスキーマ」「Swagger UI」と呼ばれる場面があります。
生成したスキーマはOpenAPI定義の一部として、Swagger UIなどのドキュメント表示にも活用できます。

リクエストボディとレスポンスボディの両方に使えますか？

使えます。POSTやPUTのリクエストJSON、GET APIのレスポンスJSON、Webhookのペイロードなど、JSON構造が分かるものならスキーマ化の起点にできます。
用途に応じて、生成後にスキーマ名や説明文を付けると管理しやすくなります。

OpenAPI 3.0と3.1の違いは気にするべきですか？

既存プロジェクトがOpenAPI 3.0で統一されている場合は、出力を取り込む前に nullable や type: null の扱いを確認してください。
新規作成や内部ツール用途なら、OpenAPI 3.1の表現に寄せても問題ないケースが多いです。

💡 プロのヒント: 自動生成はあくまで「下書き」です。生成後に各プロパティへ description や example を追加することで、チームメンバーやAPI利用者に優しい、より実用的なドキュメントへと磨き上げることができます。