SkillsAdd

zhihuihu/agent-skills · Archived

swagger-api-query

Query and analyze large Swagger/OpenAPI JSON documents on-demand to extract endpoint details and schemas without loading the entire spec.

First seen Feb 12, 2026

Installation

$ npx skills add zhihuihu/agent-skills --skill swagger-api-query
View on skills.sh ↗ GitHub repository ↗

Summary

  • 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.

Stronger alternatives

This repository is archived — consider an actively maintained alternative.

golang-swagger Similar · more installs
samber/cc-skills-golang

Golang OpenAPI/Swagger documentation with swaggo/swag — annotation comments (@Summary, @Param, …

34.8K installs
generate-swagger-docs Similar · more installs
qodex-ai/ai-agent-skills

Generate OpenAPI documentation from source code. Analyzes repository to automatically discover …

246 installs
swagger-doc-creator Similar · more installs
jeremylongshore/tons-of-skills-marketplace

Create swagger doc creator operations. Auto-activating skill for API Development. Triggers on: …

236 installs

Similar popular skills

Related neighbors and high-traction skills in the same topics — useful to compare before installing.

agent-browser Shared topics
vercel-labs/agent-browser

Browser automation CLI for AI agents. Use when the user needs to interact with websites, includ…

810.4K installs
vercel-react-best-practices Shared topics
vercel-labs/agent-skills 697.8K installs
web-design-guidelines Shared topics
vercel-labs/agent-skills

Review UI code for Web Interface Guidelines compliance. Use when asked to "review my UI", "chec…

617.3K installs
microsoft-foundry Shared topics
microsoft/azure-skills

Build, deploy, evaluate, optimize, fine-tune, and manage Microsoft Foundry agents, models, and …

576.5K installs
azure-rbac Shared topics
microsoft/azure-skills 489K installs
azure-hosted-copilot-sdk Shared topics
microsoft/azure-skills 440.4K installs
More details

Agent compatibility

Declared targets from SKILL.md / docs. Unmarked agents are not listed — the skill may still install via the CLI.

Claude Code Not declared
Cursor Not declared
Codex Not declared
GitHub Copilot Not declared
Windsurf Not declared
Gemini CLI Not declared
Cline Not declared
OpenCode Not declared

Repository health

Default branch main
Open issues 0
Status Archived

Package contents

Files included with this skill beyond the listing page.

  • skill md SKILL.md 4,014 B
  • docs SUMMARY.md 490 B

History

  1. First seen on skills.sh
  2. First recorded snapshot · 68 installs

SKILL.md

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

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)