mcpField
S
swagger-api-query

swagger-api-query

github.com/zhihuihuDevelopment068 installsUpdated 6w ago
Repository

About swagger-api-query

A command-line skill for indexing and querying OpenAPI/Swagger JSON documents. It helps developers find endpoints and inspect their details or schemas with a staged workflow.

Key features

  1. 01List API tags and endpoints
  2. 02Search endpoints by keyword
  3. 03Filter endpoints by tag
  4. 04Inspect endpoint details and schemas
  5. 05Return optional JSON output

Use cases

  1. 01Locate an authentication or user endpoint
  2. 02Review an endpoint’s methods and parameters
  3. 03Check a model’s schema fields

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/zhihuihu/agent-skills --skill swagger-api-query

After installing, type/swagger-api-queryin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

.skillsignore
CHANGELOG.md
INSTALL.md
LICENSE
package.json
README.md
agents/
openai.yaml
examples/
swagger-api.json
scripts/
swagger_query.py

Details

From the project README

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)

Comments

Markdown supported