OpenAPI Sync Until Valid

FeaturedOn demand

About OpenAPI Sync Until Valid

This loop keeps openapi.yaml in step with the routes the code actually implements. Each round runs the Redocly linter, then edits the spec based on the errors and the route code. It is started manually and runs at most 8 rounds.

Key features

01Uses the Redocly lint exit code as the judge
02Compares the spec against implemented routes each round
03Capped at 8 rounds to avoid endless retries
04Manual trigger, so the user decides when it starts

Use cases

01Syncing OpenAPI docs after adding or changing endpoints
02Clearing lint errors from the spec before a merge
03Tracking down mismatches between documentation and real routes

Goal: openapi.yaml lints without errors and matches the implemented routes.
Exit when: Stop when npx @redocly/cli lint openapi.yaml exits 0, or after 8 rounds.
Between iterations run: npx @redocly/cli lint openapi.yaml

Launch prompt

Paste into Cursor. The agent repeats the steps below until the exit condition is met.

prompt.md

Start the "OpenAPI Sync Until Valid" loop.
Goal: openapi.yaml lints without errors and matches the implemented routes.
Max iterations: 8.
Step 1: Run the lint — Run the Redocly linter and collect every error and warning reported for openapi.yaml. If the exit code is 0, the loop ends. `npx @redocly/cli lint openapi.yaml`
Step 2: Compare with routes — Read the implemented route code and find paths, parameters or responses that are missing, extra or inconsistent with the spec.
Step 3: Edit the spec — Change openapi.yaml to fix the reported errors and route differences, keeping edits minimal, then start the next round to re-check.
Between iterations run: `npx @redocly/cli lint openapi.yaml`
Exit when: Stop when npx @redocly/cli lint openapi.yaml exits 0, or after 8 rounds.

Steps

Each round runs in order; if the exit condition isn’t met, another round starts, up to 8.

Run the lint

Run the Redocly linter and collect every error and warning reported for openapi.yaml. If the exit code is 0, the loop ends.

$npx @redocly/cli lint openapi.yaml

Compare with routes

Read the implemented route code and find paths, parameters or responses that are missing, extra or inconsistent with the spec.

Edit the spec

Change openapi.yaml to fix the reported errors and route differences, keeping edits minimal, then start the next round to re-check.

Not met → next roundExits when met

Supported agents

Coding agents that can run this loop directly.

Cursor

Comments

Markdown supported