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.

Safety Notice

This listing is imported from skills.sh public index metadata. Review upstream SKILL.md and repository scripts before running.

Copy this and send it to your AI assistant to learn

Install skill "swagger-api-query" with this command: npx skills add zhihuihu/agent-skills/zhihuihu-agent-skills-swagger-api-query

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)

Source Transparency

This detail page is rendered from real SKILL.md content. Trust labels are metadata-based hints, not a safety guarantee.

Open in GitHubOpen in ClawHub

Related Skills

Related by shared tags or category signals.

Automation

vercel-composition-patterns

React composition patterns that scale. Use when refactoring components with boolean prop proliferation, building flexible component libraries, or designing reusable APIs. Triggers on tasks involving compound components, render props, context providers, or component architecture. Includes React 19 API changes.

Repository Source
23K85.8K
vercel
Automation

vercel-react-native-skills

React Native and Expo best practices for building performant mobile apps. Use when building React Native components, optimizing list performance, implementing animations, or working with native modules. Triggers on tasks involving React Native, Expo, mobile performance, or native platform APIs.

Repository Source
23K60.2K
vercel
Automation

supabase-postgres-best-practices

Postgres performance optimization and best practices from Supabase. Use this skill when writing, reviewing, or optimizing Postgres queries, schema designs, or database configurations.

Repository Source
1.6K35K
supabase