swagger-api-query

📁 zhihuihu/agent-skills 📅 1 day ago

总安装量

周安装量

#29882

全站排名

安装命令

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

Agent 安装分布

opencode 2

amp 1

openclaw 1

qoder 1

kimi-cli 1

codex 1

Skill 文档

Swagger API Query Assistant

Use scripts/swagger_query.py to index and query OpenAPI/Swagger JSON documents on-demand.

Execution Principles

Narrow down first: Prioritize list-tags, search, or tag commands
Then get details: Only call detail for target endpoints
Then view models: Only call schema when you need field definitions
Default text output: Use --format json only when downstream programs need to consume the data

Dependencies

Python 3.6+
OpenAPI/Swagger JSON document

Document Path Resolution

The script looks for documents in this order:

Explicit --spec <path> parameter
api-docs.json in current directory or parent directories
api-docs.json in skill directory or parent directories

If not found, the script will show checked paths and suggest using --spec.

Standard Workflow

1) Understand modules

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

2) Locate candidate endpoints

List all endpoints:

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

Query by tag:

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

Search by keyword:

python skills/swagger-api-query/scripts/swagger_query.py search "user"

3) View endpoint details

python skills/swagger-api-query/scripts/swagger_query.py detail "/inter-api/admin/users/{id}/status" put

If the path has only one method, you can omit the method parameter.

4) View Schema (optional)

python skills/swagger-api-query/scripts/swagger_query.py schema "UserDTO"

Structured Output

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

Common Tasks

Find login endpoint

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

List user management endpoints

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

Command Reference

Command	Description	Example
Global Parameters
`--spec <path>`	Specify document path	`--spec "D:/project/api-docs.json"`
`--format json`	JSON structured output	`--format json search "user"`
Commands
`list-tags`	List all API categories	`python scripts/swagger_query.py list-tags`
`list-all`	List all endpoint indexes	`python scripts/swagger_query.py list-all`
`tag <tag-name>`	Query endpoints by tag	`python scripts/swagger_query.py tag "User Management"`
`search <keyword>`	Search by keyword	`python scripts/swagger_query.py search "user"`
`detail <path> [method]`	View endpoint details	`python scripts/swagger_query.py detail "/api/users" get`
`schema <schema-name>`	View schema definition	`python scripts/swagger_query.py schema "UserDTO"`

Notes

detail requires explicit method (get/post/…) for paths with multiple methods
Use quotes for paths, tags, or keywords containing spaces
The script returns clear error messages (file not found, JSON parse failed, path or schema not found)

GitHub 仓库 ↗ ← 返回陌讯 Skills 聚合平台