API Discovery

Find all OpenAPI specifications in this codebase using the deterministic discover script.

Usage

/api-discover
/api-discover {directory}

Instructions

1. Determine the plugin root path:

   The plugin scripts are located relative to CLAUDE_PLUGIN_ROOT. When running as an installed plugin, this environment variable is available. You can find the discover script at:

   ${CLAUDE_PLUGIN_ROOT}/openapi-reviewer/src/discover.js
   

   To find the actual path, check the session start hook output or locate the plugin installation (typically ~/.claude/plugins/aip-api-design@*/).

2. Run the discover script:

   node "${CLAUDE_PLUGIN_ROOT}/openapi-reviewer/src/discover.js" {directory} --format markdown
   

   If CLAUDE_PLUGIN_ROOT is not set, find the plugin directory first:

   PLUGIN_DIR=$(find ~/.claude/plugins -name "aip-api-design@*" -type d 2>/dev/null | head -1)
   node "${PLUGIN_DIR}/openapi-reviewer/src/discover.js" {directory} --format markdown
   

   The script will:

   • Search recursively for files named openapi.yaml, swagger.json, etc.
   • Look in common API directories (api/, docs/, specs/, etc.)
   • Skip node_modules, .git, dist, etc.
   • Parse each spec with @readme/openapi-parser
   • Extract metadata: title, version, path count, servers, etc.
   • Detect if specs are auto-generated

   Optional flags:

   • --format json: Machine-readable output
   • --depth 5: Limit directory recursion depth

3. Save the output to:

   thoughts/api/discovery/{YYYY-MM-DD}-discovery.md
   

4. Present findings to user:

   • List specs found with path and metadata
   • Highlight any parse errors
   • Recommend running /api-review {spec-path} on specific specs
   • If multiple specs, ask which one to review first

Output Fields

For each spec found:

Field	Description
path	Relative path to spec file
type	openapi-3.x, openapi-3.1, swagger-2.x
title	API title from info.title
apiVersion	Version from info.version
pathCount	Number of paths
operationCount	Number of operations (GET, POST, etc.)
servers	Server URLs if defined
isGenerated	Whether spec appears auto-generated

What It Searches For

Filenames:

• openapi.yaml, openapi.yml, openapi.json
• swagger.yaml, swagger.yml, swagger.json
• api.yaml, api.yml, api.json
• Any file containing openapi or swagger in name

Directories prioritized:

• api/, docs/, spec/, specs/
• openapi/, swagger/, schema/, schemas/

Skipped:

• node_modules/, .git/, dist/, build/, coverage/

Example Session

User: /api-discover

Claude: Running discovery script...

[Runs: node openapi-reviewer/src/discover.js . --format markdown]

Found 2 OpenAPI specifications:

1. **Pet Store API** (`api/openapi.yaml`)
   - OpenAPI 3.0.3, 15 paths, 24 operations

2. **Internal Admin API** (`admin/swagger.json`)
   - Swagger 2.0, 8 paths, 12 operations
   - Auto-generated by swagger-jsdoc

Which spec would you like to review? Run `/api-review api/openapi.yaml` to analyze against AIP rules.

Related Commands

• /api-review {spec} - Review spec against AIP rules
• /api-discover-nestjs - (future) Discover NestJS code-first APIs