OpenAPI Guard

Check an OpenAPI 3.x contract against Spring Boot Java/Kotlin, NestJS TypeScript, Express (TypeScript or JavaScript), and AWS Lambda (API Gateway routeKey dispatch) endpoints without opening an editor. Analysis runs locally and does not upload source code, specifications, diagnostics, or repository metadata.

Run without installing

From the project containing your OpenAPI document and implementation:

npx @stackblender/openapi-guard .

OpenAPI Guard finds OpenAPI 3.x documents by content (whatever their filename) and supported source files. Use versioned JSON when another tool or coding agent consumes the result:

npx @stackblender/openapi-guard . --format json

Install in a project

npm install --save-dev @stackblender/openapi-guard

Then add a repeatable project command:

{
  "scripts": {
    "openapi:check": "openapi-guard ."
  }
}

Options and exit codes

Usage: openapi-guard [workspace] [options]

Options:
  --spec <path>       Workspace-relative OpenAPI specification; may be
                      repeated (default: every OpenAPI 3.x file found)
  --include <glob>    Source include glob; may be repeated
  --exclude <glob>    Additional exclude glob; may be repeated
  --implementation-path-prefix <path>
                      Prefix applied to discovered implementation routes
  --format <format>   text (default) or json
  -h, --help          Show help

Exit code 0 means the contract is clean, 1 means contract drift was found, and 2 means configuration, discovery, parsing, or execution failed.

MCP

The package also installs openapi-guard-mcp, a local read-only MCP server using standard input/output. An MCP client can launch a pinned package version with:

command: npx
arguments: --yes --package=@stackblender/[email protected] openapi-guard-mcp
working directory: /absolute/path/to/project
transport: stdio

It exposes check_openapi_contract and uses the same versioned result as the CLI. Pin the package version in persistent agent configuration so an update is a deliberate choice.

Current scope

OpenAPI Guard detects missing implementations, undocumented implementations, and HTTP-method mismatches for Spring MVC (Java and Kotlin), NestJS, and Express routes (TypeScript or JavaScript, with routers mounted across files), and for AWS Lambda route maps, switch dispatch, and alias maps keyed by API Gateway "METHOD /path" route keys. For Spring it resolves mappings inherited from interfaces and base classes (including openapi-generator interface-only and delegate projects), constant paths, ${...} placeholders from application.properties / application.yml, and aligns OpenAPI servers base paths with server.servlet.context-path. It skips computed or unresolved routing rather than guessing and lists it under limitations in the report; a custom Lambda router's routes can be declared in openapi-guard.routes.json. Parameters, request and response bodies, DTO/schema comparison, custom decorators, and runtime route discovery are not currently analyzed.

See the CLI and MCP documentation, get support, report a bug, or report a security concern privately.