route-to-openapi

route-to-openapi

ソースコード内のルート／エンドポイント定義を自動的にスキャンし、OpenAPI 3.0.3 仕様に準拠した RESTful API ドキュメントを生成します。

主要な Web フレームワークに対応しており、フレームワークを自動検出します。HTTP メソッド、パス、パラメーター、リクエストボディ、レスポンスモデル、ドキュメントコメントを抽出し、Swagger UI や Redoc にインポートできる標準的な OpenAPI 仕様ファイルを出力します。

クイックスタート

# Scan source directory, output OpenAPI spec in JSON format
python scripts/generate_api_doc.py ./src

# Specify output format and file
python scripts/generate_api_doc.py ./src --format yaml --output api-spec.yaml

# Specify framework and API metadata
python scripts/generate_api_doc.py ./app --framework flask --title "My API" --version 2.0.0

# Add server URLs
python scripts/generate_api_doc.py ./routes --server http://localhost:3000 --server https://api.example.com

対応フレームワーク

言語	フレームワーク	解析方法
Python	Flask	AST 解析（デコレーター＋型アノテーション＋docstring）
Python	FastAPI	AST 解析（デコレーター＋Pydantic モデル＋型アノテーション）
Python	Django REST Framework	AST 解析（@api_view デコレーター）
JavaScript/TypeScript	Express.js	正規表現によるマッチング（app.get() / router.get() ＋ JSDoc）
Go	Gin	正規表現によるマッチング（r.GET() / group.GET() ＋コメント）
Go	Echo	正規表現によるマッチング（e.GET() ＋コメント）

抽出機能

スクリプトは以下の情報を自動的に抽出します。

• HTTP メソッド：GET / POST / PUT / DELETE / PATCH など
• ルートパス：各フレームワークのパスパラメーター形式を OpenAPI の {param} 形式に自動変換します
• パスパラメーター：ルートパターンから抽出します（型推論付き）
• クエリパラメーター：関数シグネチャから抽出します（Python フレームワーク）
• リクエストボディ：型アノテーションと Pydantic モデルから推定します（FastAPI）
• レスポンスモデル：response_model パラメーターから抽出します（FastAPI）
• エンドポイントの説明：docstring / JSDoc / インラインコメントから抽出します
• タグによるグループ化：ソースファイルのモジュール名で自動的にグループ化します

パスパラメーター形式の変換

フレームワーク	ソース形式	変換後
Flask	<int:user_id>	{user_id}（型：integer）
FastAPI	{user_id}	{user_id}（変更なし）
Express	:user_id	{user_id}
Gin/Echo	:user_id	{user_id}

パラメーター

パラメーター	説明	デフォルト
source_dir	スキャンするソースディレクトリ（必須）	-
-f, --format	出力形式：json または yaml	json
-o, --output	出力ファイルのパス	stdout
--framework	特定のフレームワークを指定します（自動検出をスキップ）	自動検出
--title	API ドキュメントのタイトル	API Documentation
--version	API のバージョン番号	1.0.0
--description	API の説明文	空
--server	サーバー URL（複数指定可能）	なし

出力例

{
  "openapi": "3.0.3",
  "info": {
    "title": "My API",
    "version": "1.0.0"
  },
  "paths": {
    "/users": {
      "get": {
        "summary": "List all users",
        "operationId": "list_users",
        "tags": ["users"],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": { "type": "integer" }
          }
        ],
        "responses": {
          "200": { "description": "Successful response" }
        }
      }
    },
    "/users/{user_id}": {
      "get": {
        "summary": "Get user by ID",
        "operationId": "get_user",
        "tags": ["users"],
        "parameters": [
          {
            "name": "user_id",
            "in": "path",
            "required": true,
            "schema": { "type": "integer" }
          }
        ],
        "responses": {
          "200": { "description": "Successful response" }
        }
      }
    }
  }
}

前提条件

• Python 3.8+
• 追加の依存関係は不要です — Python 標準ライブラリのみを使用します
• スキャン対象のプロジェクトが、上記の対応 Web フレームワークのいずれかを使用している必要があります