Skip to content

commandBackend and APIs

Update OpenAPI

Brings your OpenAPI spec in line with changed routes and validates the file, so the spec matches what the server does.

npx workspacetemplates add update-openapi --tool claude-code

Writes 1 file to .claude/commands/

.claude/commands/update-openapi.md15 lines · 1.2 KBFile
---
description: Brings your OpenAPI spec in line with changed routes and validates the file, so the spec matches what the server does.
argument-hint: "[routes or files that changed]"
---

Update the OpenAPI spec for these changes: $ARGUMENTS (if empty, use `git diff main --stat` to find changed routes).

1. Locate the spec (openapi.yaml, openapi.json, swagger.*) and whether it is hand-written or generated. If generated, run the project's generate command instead of editing by hand.
2. For each changed route, compare the code with the spec: path, method, parameters, request body, response codes, response schemas, security.
3. Edit only the differing parts. Reuse `components/schemas` and `$ref` rather than copying objects. Keep operationIds unique and follow the file's existing style.
4. Mark deprecated routes with `deprecated: true`, not by deleting them.
5. Validate with the tool in the repo or `npx @redocly/cli lint <file>` (or `npx swagger-cli validate <file>`). Fix every error.
6. Classify each change as breaking (removed or renamed field, new required field, changed type) or compatible.

Show a summary table of changes with the breaking ones first, plus the diff. Ask before writing the file if more than five operations change.

What it does

Clients build against whatever the spec says, so an out-of-date file does real damage. This command compares the routes in the code with the paths in the spec and edits only what differs.

After editing it runs a validator and, where possible, checks that the spec still lints cleanly. Breaking changes are called out so you can decide on a version bump.

Example

you › /update-openapi orders routes

agent › Updated 3 operations: GET /orders (new status filter), POST /orders (items now required), DELETE /orders/{id} (new 409).
Breaking: POST /orders items required.
Redocly lint: 0 errors, 1 warning (missing example).

Questions

What if the spec is generated from code?
It runs your generator rather than hand-editing, so the next build does not overwrite the changes.
Does it change my API version?
No. It labels the breaking changes and leaves the version number decision with you.
  • Add Caching

    CommandBackend and APIs

    Free
  • Add Endpoint

    CommandBackend and APIs

    Free
  • Add Health Check

    CommandBackend and APIs

    Free
  • Add Pagination

    CommandBackend and APIs

    Free