crawl-apis

Crawl APIs — Discover and Register API Definitions

Scan a codebase directory for API definitions and propose registry entries.

Arguments

• $1 — Path to scan (required). Absolute or relative path to the codebase to crawl.
• --domain <name> — Domain to assign discovered APIs to (optional, will ask if omitted).
• --write — Write proposed entries to registry immediately (default: preview only).

If no path is provided, ask the user which directory to scan.

Workflow

1. Discover Type-to-Folder Mapping

Read models/registry-mapping.yaml to find:

• The folder path for api_contract entries
• The folder path for api_endpoint entries
• The _template.md in each folder for frontmatter structure

Never hardcode paths. Always derive from the YAML.

2. Scan for API Definitions

Search the target directory for API-related files. Use these detection patterns:

OpenAPI / Swagger specs:

# Find OpenAPI/Swagger YAML and JSON files

• Glob: **/{openapi,swagger}*.{yaml,yml,json}, **/api-spec*.{yaml,yml,json}
• Content match: files containing openapi: or swagger: at the top level

REST route definitions (Node.js/Express/Fastify/Hono):

• Grep for patterns: router\.(get|post|put|delete|patch), app\.(get|post|put|delete|patch), @Get|@Post|@Put|@Delete (NestJS decorators)
• Look in: **/routes/**, **/controllers/**, **/handlers/**, **/api/**

GraphQL schemas:

• Glob: **/*.graphql, **/*.gql
• Content match: files containing type Query, type Mutation, schema {

gRPC / Protobuf:

• Glob: **/*.proto
• Content match: service <Name> blocks

Python (FastAPI/Flask/Django REST):

• Grep for: @app.route, @router.get|post|put|delete, @api_view, class.*ViewSet

3. Extract API Information

For each discovered API, extract:

Field	Source
name	OpenAPI info.title, route prefix, GraphQL type name, proto service name
description	OpenAPI info.description, JSDoc/docstring if available
protocol	REST, GraphQL, gRPC, async (inferred from file type)
endpoints	Individual route paths / operations / queries+mutations
status	draft (always — human reviews and promotes)