How do I install the Swagger API Query skill?

Run npx skillmds@latest add zhihuihu/swagger-api-query in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Swagger API Query safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Swagger API Query?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Swagger API Query free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Swagger API Query?

zhihuihu (@zhihuihu) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Swagger API Query by zhihuihu — Agent Skill

Name: Swagger API Query
Author: zhihuihu

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.

zhihuihu 784a0ae 10 files · 35.6 KB Updated Sep 17, 2026

File contents

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)

---name: swagger-api-querydescription: 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.---# Swagger API Query AssistantUse `scripts/swagger_query.py` to index and query OpenAPI/Swagger JSON documents on-demand.## Execution Principles1. **Narrow down first**: Prioritize `list-tags`, `search`, or `tag` commands2. **Then get details**: Only call `detail` for target endpoints3. **Then view models**: Only call `schema` when you need field definitions4. **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 ResolutionThe script looks for documents in this order:1. Explicit `--spec <path>` parameter2. `api-docs.json` in current directory or parent directories3. `api-docs.json` in skill directory or parent directoriesIf not found, the script will show checked paths and suggest using `--spec`.## Standard Workflow### 1) Understand modules```bashpython skills/swagger-api-query/scripts/swagger_query.py list-tags```### 2) Locate candidate endpoints**List all endpoints:**```bashpython skills/swagger-api-query/scripts/swagger_query.py list-all```**Query by tag:**```bashpython skills/swagger-api-query/scripts/swagger_query.py tag "User Management"```**Search by keyword:**```bashpython skills/swagger-api-query/scripts/swagger_query.py search "user"```### 3) View endpoint details```bashpython 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)```bashpython skills/swagger-api-query/scripts/swagger_query.py schema "UserDTO"```## Structured Output```bashpython 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```bashpython 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```bashpython 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)

Frequently asked questions