skillZs
★ LIVE SKILL TAGS ★
>>> LIVE SKILLS INDEX <<<
* OPEN SOURCE *
NO LOGIN, NO TRACKING
※ REAL INSTALL DATA ※
← back to all skills
zhihuihu/agent-skills68 installs

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-query
view source ↗

Is 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

  1. Narrow down first: Prioritize list-tags, search, or tag commands
  2. Then get details: Only call detail for target endpoints
  3. Then view models: Only call schema when you need field definitions
  4. 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:

  1. Explicit --spec <path> parameter
  2. api-docs.json in current directory or parent directories
  3. 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

CommandDescriptionExample
Global Parameters
--spec <path>Specify document path--spec "D:/project/api-docs.json"
--format jsonJSON structured output--format json search "user"
Commands
list-tagsList all API categoriespython scripts/swagger_query.py list-tags
list-allList all endpoint indexespython scripts/swagger_query.py list-all
tag <tag-name>Query endpoints by tagpython scripts/swagger_query.py tag "User Management"
search <keyword>Search by keywordpython scripts/swagger_query.py search "user"
detail <path> [method]View endpoint detailspython scripts/swagger_query.py detail "/api/users" get
schema <schema-name>View schema definitionpython 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)

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>