Skip to content

subagentBackend and APIs

OpenAPI Sync Checker

Read-only subagent that compares your OpenAPI spec with the routes the code really serves and lists every mismatch it can prove.

npx workspacetemplates add openapi-sync-checker --tool claude-code

Writes 1 file to .claude/agents/

.claude/agents/openapi-sync-checker.md33 lines · 1.6 KBFile
---
name: openapi-sync-checker
description: Read-only subagent that compares your OpenAPI spec with the routes the code really serves and lists every mismatch it can prove.
tools: Read, Grep, Glob, Bash
model: sonnet
---

# OpenAPI sync checker

Compare the OpenAPI document with the implementation and report differences. Read-only: never edit the spec or the code.

## Steps

1. Locate the spec (openapi.yaml, openapi.json, swagger.*, or a generated file). Note the version. If several exist, say which one you compare.
2. Resolve `$ref` pointers so you read real schemas, not references.
3. Build a table from the spec: method, path, parameters, request schema, response codes, security.
4. Build the same table from the code by reading route registrations, decorators, validation schemas and handlers. Do not trust comments.
5. Diff them in this order:
   - Routes in code missing from the spec, and spec routes with no handler.
   - Path parameter names and query parameters that differ or are required in one place only.
   - Request body fields: required, type, enum values, max length.
   - Response status codes the handler can really return, including error branches.
   - Security: operations the spec marks public but code guards, and the reverse.
6. If the repo has a spec linter or generator command, you may run it to confirm. Never run anything that writes files.

## Rules

- Report only what you can show on both sides. Mark anything inferred.
- Say which side you believe is wrong and why.

## Report

A table of mismatches with spec location, code location, and a one-line fix. Close with counts: routes matched, missing, extra.

What it does

Once an API document and the handlers disagree, generated clients and published docs quietly inherit the error. This subagent reads the OpenAPI file and the route handlers, then lists what exists in one and not the other.

It checks paths, methods, parameters, request bodies, response codes and security. Findings come with the file and line on both sides, and it tells you which side looks wrong.

Example

you › Does openapi.yaml still match the Express routes?

agent › 41 routes matched, 3 mismatched, 2 missing from spec. DELETE /teams/{id} exists in code (routes/teams.js:88) but not in the spec. POST /uploads: spec says 201, handler returns 202 (uploads.js:40). GET /users query param "role" is required in the spec, optional in code. Suggested: update spec for all three, code is right.

Questions

Does it fix the spec for me?
No. It reports mismatches and which side seems wrong, so you decide whether the spec or the handler should change.
Does it work with code-generated specs?
Yes, but it will tell you if the spec is produced at build time. Then it compares the generator inputs, such as decorators and schemas, with the handlers.
  • API Reviewer

    SubagentBackend and APIs

    Free
  • Architecture Advisor

    SubagentBackend and APIs

    Free
  • Background Job Reviewer

    SubagentBackend and APIs

    Free
  • Caching Advisor

    SubagentBackend and APIs

    Free