mcpField
G
generate-swagger-docs

generate-swagger-docs

github.com/qodex-ai開発47253 回インストール42 週間前に更新
リポジトリ

generate-swagger-docs について

generate-swagger-docsは、コードベースからSwagger/OpenAPIドキュメントを生成するスキルです。一般的なフレームワークを検出し、OpenAPI 3.0仕様と操作可能なHTMLドキュメントを作成します。

主な機能

  1. 01コードベース内のAPIエンドポイントをスキャン
  2. 02Webフレームワークを自動検出
  3. 03OpenAPI 3.0仕様を生成
  4. 04操作可能なHTMLドキュメントを作成
  5. 05設定を保存して次回実行に利用

活用シーン

  1. 01既存APIのドキュメント作成
  2. 02ExpressやFastAPIプロジェクトのエンドポイント整理
  3. 03共有可能なSwagger UIページの生成

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/qodex-ai/ai-agent-skills --skill generate-swagger-docs

インストール後、Claude Code で/generate-swagger-docsを入力して読み込まれたか確認します。

同梱ファイルgenerate-with-key.sh

詳細

Swagger ドキュメントを生成する

API キーを自動設定し、コードベースから OpenAPI ドキュメントを数秒で生成します。

動作の仕組み

このスキルは、Swagger／OpenAPI ドキュメントの生成を自動化します。

  1. API キーの設定 - OpenAI API キーを受け取り、環境変数として設定します
  2. 初期化 - apimesh ツールをダウンロードしてセットアップします
  3. 自動処理 - ツールがコードベースを分析し、ドキュメントを生成します
  4. 出力 - 出力ファイルは apimesh/ ディレクトリに保存されます

セットアップ要件

このスキルを使用するには OpenAI API キーが必要です。まだお持ちでない場合は、OpenAI のプラットフォームから取得してください。

おすすめ：API キーを使ったクイックセットアップ

このスキルを使用する最も簡単な方法は、API キーを直接渡すことです。

/Users/ankits/.claude/skills/generate-swagger-docs/generate-with-key.sh "sk-proj-your-api-key-here"

これにより、次の処理が行われます。

  1. OpenAI API キーを引数として受け取ります
  2. apimesh/ ディレクトリを作成し、apimesh ツールをダウンロードします
  3. 環境変数を正しく設定します
  4. Swagger ドキュメントを自動生成します
  5. 出力ファイルの場所を表示します

自動実行フロー

このスキルを実行すると、次の処理が行われます。

  1. 初回実行時： OpenAI API キー（sk-proj- で始まるもの）の入力を求められます

    • キーはローカルに保存され、以降の実行で使用されます
    • キーがバージョン管理にコミットされることはありません

  2. 2 回目以降の実行時： 保存された API キーが自動的に使用されます

    • 設定を消去しない限り、キーの入力を再度求められることはありません

  3. フレームワークの検出： API フレームワークが自動的に検出されます

    • 対応対象：Express、NestJS、FastAPI、Django、Rails、Go など

このスキルの機能

  • リポジトリをスキャンして API エンドポイントを検出します
  • Web フレームワーク（Django、Flask、FastAPI、Express、NestJS、Rails、Go）を検出します
  • OpenAPI 3.0 仕様（swagger.json）を生成します
  • インタラクティブな HTML ドキュメント（apimesh-docs.html）を作成します

出力

  • apimesh/swagger.json - OpenAPI 3.0 仕様
  • apimesh/apimesh-docs.html - インタラクティブな Swagger UI（単体で動作し、共有可能）
  • apimesh/config.json - 保存された設定（設定が含まれるため、このファイルを gitignore に追加してください）

重要な注意事項

  • LLM による分析には OpenAI API キーが必要です
  • 生成された config.json にはシークレットが含まれるため、.gitignore に追加してください
  • フレームワークは自動的に検出されますが、必要に応じて手動で指定することもできます
  • このツールはパブリックリポジトリとプライベートリポジトリの両方に対応しています

API キーの設定方法

方法 1：ラッパースクリプト（おすすめ） ✓

環境変数を正しく引き継ぐ、付属のラッパースクリプトを使用します。

/Users/ankits/.claude/skills/generate-swagger-docs/generate-with-key.sh "sk-proj-your-api-key-here"

この方法が最適な理由：

  • API キーを Python のサブプロセスに正しく渡します
  • TTY 以外の環境では、対話型の入力プロンプトが表示されません
  • 環境変数を正しく引き継ぎます
  • 明確な成功／エラーメッセージを表示します
方法 2：保存済みの設定を使用する

方法 1 で初回実行した後、キーは apimesh/config.json に保存されます。2 回目以降の実行では、ローカルのセットアップを信頼できる場合、キーを省略できます。

/Users/ankits/.claude/skills/generate-swagger-docs/generate-with-key.sh

重要： config.json ファイルをバージョン管理にコミットしないでください。.gitignore に追加してください。

方法 3：apimesh を手動でセットアップする

より細かく制御する必要がある場合は、apimesh を直接ダウンロードして実行します。

export OPENAI_API_KEY="sk-proj-your-api-key-here"
mkdir -p apimesh && \
  curl -sSL https://raw.githubusercontent.com/qodex-ai/apimesh/refs/heads/main/run.sh -o apimesh/run.sh && \
  chmod +x apimesh/run.sh && \
  cd apimesh && \
  OPENAI_API_KEY="$OPENAI_API_KEY" ./run.sh

注： 上記のとおり、OPENAI_API_KEY をサブプロセスに明示的に渡す必要があります。

コメント

Markdown 対応