Blog

既存のリクエストからOpenAPI Specを生成する方法

INEZA Felin-Michel

INEZA Felin-Michel

5 12月 2025

既存のリクエストからOpenAPI Specを生成する方法

OpenAPI仕様をゼロから記述するのは、特にAPIが既に稼働している場合には多くの時間を要します。多くのチームは、ドキュメントがほとんど、あるいは全くないプロジェクトを引き継いだり、開発初期に急いで構築されたAPIを扱ったりしています。このような場合、ドキュメントを作成する最も実用的な方法は、既存のAPIリクエストから直接OpenAPI仕様を生成することです。

このガイドでは、このアプローチが機能する理由、役立つツール、そして実際のリクエストをチームが信頼できるクリーンで再利用可能なOpenAPI仕様に変換する方法を説明します。

💡
cURLコマンド、HARファイル、Postmanコレクション、または生のAPIログが既にある場合、OpenAPI仕様をゼロから書く必要はありません。Apidogはこれらのすべてのフォーマットをインポートし、瞬時にクリーンで構造化されたOpenAPI仕様に変換できます。各リクエストを分析し、モデルを自動生成し、すべてを一箇所で調整できるようにします。これにより、手作業の時間を節約しながら、ドキュメントの正確性と一貫性を維持できます。
ボタン

方法1: 「コードファースト」アプローチ

この方法は、バックエンドアプリケーションコードに直接アノテーションやライブラリを追加できる場合に機能します。

仕組み

Webフレームワークにライブラリをインストールし、それがコード（ルート、コントローラー、モデル）を検査し、リアルタイムでOpenAPI仕様を生成します。

人気のあるライブラリ:

FastAPI (Python) の例:

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Item(BaseModel):
    name: str
    price: float

@app.post("/items/", response_model=Item)
async def create_item(item: Item):
    """
    Create a new item in the database.
    - **name**: The item's name
    - **price**: The item's price in USD
    """
    return item

# このコードは、/docs または /openapi.json で完全なOpenAPI仕様を自動生成します

長所:

短所:

方法2: 「トラフィック分析」アプローチ

これは賢い「外部からの」アプローチです。クライアントとAPI間の実際のHTTPトラフィックをキャプチャし、それを分析して仕様を推測します。

仕組み

プロキシまたはネットワークスニファとして機能するツールを使用します。すべてのAPIトラフィックはそれを経由します。ツールはリクエストとレスポンス（URL、メソッド、ヘッダー、ボディ）を分析し、APIのモデルを構築します。

人気のあるツール:

プロセス:

  1. アプリケーションまたはクライアントを構成し、プロキシツールを介してトラフィックをルーティングします。
  2. 主要なAPIワークフロー（ログイン、データ作成、データ取得など）を実行します。
  3. ツールがパターンを観察し、暫定的なOpenAPI仕様を生成します。

長所:

短所:

方法3: 「リクエストコレクション」アプローチ

これは、開発者やチームにとって最も実用的で効率的な方法であることがよくあります。リクエストを送信するだけでなく、API設計も理解する高度なAPIクライアントを使用します。リクエストのコレクションを構築し、ツールがそれらをクリーンなOpenAPI仕様として構造化およびエクスポートするのを支援します。

これは、Apidog の真価が発揮されるところです。このワークフローのために構築されています。

ボタン

Apidogでの仕組み

1. 通常通りリクエストを送信する: ワークフローを変更する必要はありません。Apidogを使用して既存のAPIエンドポイントをテストおよびデバッグします。GET、POST、PUT、DELETE リクエストを送信すると、Apidogはすべての詳細をキャプチャします。

2. Apidogにモデルを構築させる: 舞台裏で、Apidogは作業中にAPIの構造を理解し始めます。エンドポイント、パラメーター、リクエストボディ、レスポンススキーマを認識します。

3. ドキュメントに整理する: ApidogはリクエストをリアルタイムでAPIドキュメントに変換できます。 あなたのアドホックなリクエストは、ツール内で構造化されたナビゲーション可能なAPIドキュメントページになります。説明を追加したり、エンドポイントをフォルダーにグループ化したり、自動推論された詳細を整理したりできます。

4. 仕様をエクスポートする: コレクションが正確で適切に記述されたら、エクスポートします。そして、ユーザーはOpenAPI仕様を標準のYAMLまたはJSON形式でワンクリックでエクスポートできます。この仕様は、Swagger UIで使用したり、他のツールにインポートしたり、リポジトリにコミットしたりする準備ができています。

長所:

短所:

方法4: 手動作成アプローチ

時には、Swagger Editor や Stoplight Studio のようなエディターで、手動で仕様を構築する必要があります。これは、上記のメソッドと併用されることがよくあります。

  1. リクエストコレクションを参照として使用する: Postmanコレクション、cURLコマンド、またはApidogプロジェクトをセカンドスクリーンで開いておきます。
  2. 仕様を段階的に構築する: 参照内の各エンドポイントについて、手動でOpenAPI YAML/JSONに変換します。これにより、各パラメーターとレスポンスについて深く考えることになります。
  3. 例で検証する: エディターのプレビューを使用して、仕様が実際のAPIの動作と一致していることを確認します。

長所:

短所:

リクエストからOpenAPI仕様を生成するためのベストプラクティス

どの方法を選択するかにかかわらず、以下の原則に従ってください:

  1. 小さく始める: 1つのコアエンドポイント（例: GET /users）を選びます。それを完全に生成またはドキュメント化してから、拡張していきます。
  2. 早期かつ頻繁に検証する: OpenAPI仕様を使用して、すぐにモックサーバーを生成します。それが実際のAPIのように動作するか確認します。これにより、不一致を迅速に発見できます。
  3. 繰り返し改善する: 最初に生成された仕様は粗いでしょう。それを下書きとして扱います。説明や例を追加し、スキーマ定義を厳密にします。
  4. エラー応答を含める: これは見落とされがちです。仕様に4xxおよび5xxのエラー応答形式が記述されていることを確認してください。
  5. 認証を忘れない: APIがどのように保護されているか（APIキー、OAuth2など）を securitySchemes セクションに記述してください。

結論: あなたの設計図が待っています

既存のリクエストからOpenAPI仕様を生成することは、単に可能であるだけでなく、成熟したAPIプロジェクトに秩序をもたらすための実用的な必要性です。コードファーストのライブラリ、トラフィック監視ツール、またはApidogのような強力なAPIクライアントのいずれを選択するにしても、明確性、自動化、およびコラボレーションに投資していることになります。

選択するメソッドは、コードベースの制御、時間の制約、チームのワークフローなど、あなたの状況によって異なります。しかし、目標は同じです。それは、リクエストログ、cURLコマンド、および暗黙的な知識に内在する情報を、APIを前進させるための明示的で機械可読な契約に変換することです。

APIの複雑さを闇の中に放置するのをやめましょう。既にあるリクエストから始め、適切なツールを使用し、その不可欠なOpenAPI設計図を構築しましょう。未来のあなた自身と、あなたのAPIを使用する必要があるすべての人々が感謝するでしょう。

ボタン

ApidogでAPIデザイン中心のアプローチを取る

APIの開発と利用をよりシンプルなことにする方法を発見できる

無料会員登録ダウンロード