mcpField
S
swagger-api-query

swagger-api-query

github.com/zhihuihu開発068 回インストール6 週間前に更新
リポジトリ

swagger-api-query について

OpenAPI/Swagger JSONドキュメントをインデックス化して検索するコマンドラインスキルです。開発者がエンドポイントを絞り込み、詳細やスキーマを段階的に確認できます。

主な機能

  1. 01APIタグとエンドポイントの一覧表示
  2. 02キーワードによる検索
  3. 03タグによる絞り込み
  4. 04詳細とスキーマの確認
  5. 05JSON形式での出力

活用シーン

  1. 01認証やユーザー関連のエンドポイント検索
  2. 02メソッドやパラメーターの確認
  3. 03モデルのスキーマ項目の確認

インストール

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

$npx skills add https://github.com/zhihuihu/agent-skills --skill swagger-api-query

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

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

.skillsignore
CHANGELOG.md
INSTALL.md
LICENSE
package.json
README.md
agents/
openai.yaml
examples/
swagger-api.json
scripts/
swagger_query.py

詳細

Swagger API クエリアシスタント

scripts/swagger_query.py を使って、OpenAPI／Swagger JSON ドキュメントをオンデマンドでインデックス化し、クエリを実行します。

実行の原則

  1. まず対象を絞り込みます：list-tags、search、または tag コマンドを優先します
  2. 次に詳細を取得します：対象エンドポイントに対してのみ detail を呼び出します
  3. 次にモデルを確認します：フィールド定義が必要な場合にのみ schema を呼び出します
  4. デフォルトはテキスト出力です：後続のプログラムでデータを利用する必要がある場合にのみ --format json を使います

依存関係

  • Python 3.6+
  • OpenAPI／Swagger JSON ドキュメント

ドキュメントパスの解決

スクリプトは次の順序でドキュメントを検索します。

  1. 明示的に指定した --spec <path> パラメーター
  2. 現在のディレクトリまたは親ディレクトリにある api-docs.json
  3. スキルディレクトリまたは親ディレクトリにある api-docs.json

見つからない場合、確認したパスを表示し、--spec の使用を提案します。

標準的なワークフロー

1) モジュールを理解する
python skills/swagger-api-query/scripts/swagger_query.py list-tags
2) 候補となるエンドポイントを見つける

すべてのエンドポイントを一覧表示します：

python skills/swagger-api-query/scripts/swagger_query.py list-all

タグでクエリを実行します：

python skills/swagger-api-query/scripts/swagger_query.py tag "User Management"

キーワードで検索します：

python skills/swagger-api-query/scripts/swagger_query.py search "user"
3) エンドポイントの詳細を確認する
python skills/swagger-api-query/scripts/swagger_query.py detail "/inter-api/admin/users/{id}/status" put

パスにメソッドが1つしかない場合は、メソッドパラメーターを省略できます。

4) スキーマを確認する（任意）
python skills/swagger-api-query/scripts/swagger_query.py schema "UserDTO"

構造化出力

python skills/swagger-api-query/scripts/swagger_query.py --format json search "login"
python skills/swagger-api-query/scripts/swagger_query.py --spec "D:/my/project/api-docs.json" --format json detail "/api/auth/login" post

よくあるタスク

ログインエンドポイントを見つける
python skills/swagger-api-query/scripts/swagger_query.py search "login"
python skills/swagger-api-query/scripts/swagger_query.py detail "/api/auth/login" post
ユーザー管理エンドポイントを一覧表示する
python skills/swagger-api-query/scripts/swagger_query.py tag "User Management"
python skills/swagger-api-query/scripts/swagger_query.py detail "/api/users" get

コマンドリファレンス

コマンド説明例
グローバルパラメーター
--spec <path>ドキュメントパスを指定します--spec "D:/project/api-docs.json"
--format jsonJSON 構造化出力--format json search "user"
コマンド
list-tagsすべての API カテゴリーを一覧表示しますpython scripts/swagger_query.py list-tags
list-allすべてのエンドポイントインデックスを一覧表示しますpython scripts/swagger_query.py list-all
tag <tag-name>タグでエンドポイントを検索しますpython scripts/swagger_query.py tag "User Management"
search <keyword>キーワードで検索しますpython scripts/swagger_query.py search "user"
detail <path> [method]エンドポイントの詳細を確認しますpython scripts/swagger_query.py detail "/api/users" get
schema <schema-name>スキーマ定義を確認しますpython scripts/swagger_query.py schema "UserDTO"

注意事項

  • 複数のメソッドがあるパスでは、detail に明示的なメソッド（get/post/...）が必要です
  • スペースを含むパス、タグ、キーワードには引用符を使います
  • スクリプトは明確なエラーメッセージを返します（ファイルが見つからない、JSON の解析に失敗した、パスまたはスキーマが見つからないなど）

コメント

Markdown 対応