swagger-api-query
Query and analyze large Swagger/OpenAPI JSON documents on-demand to extract endpoint details and schemas without loading the entire spec. Use for API discovery, searching by tag/keyword, understanding request/response structures, and tracing data models. Invoke when user asks to "find an endpoint", "search for login/upload/user APIs", or "explain a schema". Use --spec to specify document path if not in current directory, and --format json for structured output.
How do I install this agent skill?
npx skills add https://github.com/zhihuihu/agent-skills --skill swagger-api-queryIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill is designed to query and summarize OpenAPI/Swagger documentation using a local Python script. While the core functionality is legitimate, it presents a surface for indirect prompt injection if the documentation being queried contains malicious instructions. Additionally, the skill is sourced from a non-whitelisted GitHub repository.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
- Runlayerwarn
9/10 files flagged
What does this agent skill do?
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, ortagcommands - Then get details: Only call
detailfor target endpoints - Then view models: Only call
schemawhen you need field definitions - Default text output: Use
--format jsononly 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.jsonin current directory or parent directoriesapi-docs.jsonin 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
detailrequires 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)
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/zhihuihu/agent-skills/swagger-api-query">View swagger-api-query on skillZs</a>