mcpField
S
swagger-api-query

swagger-api-query

github.com/zhihuihu开发068 次安装7 周前更新
代码仓库

关于 swagger-api-query

通过命令行索引和查询 OpenAPI/Swagger JSON 文档的技能，供开发者查找端点并查看详情或架构；流程强调先筛选，再检查目标。

主要功能

  1. 01列出 API 标签和端点
  2. 02按关键词搜索端点
  3. 03按标签筛选端点
  4. 04查看端点详情和架构
  5. 05可选输出 JSON

适用场景

  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

如果路径只有一种方法，可以省略方法参数。

4) 查看 Schema（可选）
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>查看 Schema 定义python scripts/swagger_query.py schema "UserDTO"

注意事项

  • 对于包含多种方法的路径，detail 需要显式指定方法（get/post/...）
  • 路径、标签或关键词中包含空格时，请使用引号
  • 脚本会返回清晰的错误信息（文件未找到、JSON 解析失败、路径或 Schema 未找到）

评论

支持 Markdown