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)