OpenAPI Compatibility Checklist

Catch breaking changes before they ship. Diff the old and new OpenAPI spec, then confirm each category below.

When to use this

  • Before bumping your OpenAPI version.
  • Before merging a spec PR that touches existing endpoints.
  • When a consumer reports an unexpected breakage.

How this checklist works

Some items run a quick local check (e.g. scanning sample responses for secrets or PII). Others are manual confirmations or open another tool. When you finish, copy the report as Markdown to paste into your PR description, ticket, or Slack.

Privacy

This page is a static HTML file. The checklist component runs locally in your browser. The raw text you paste into the Run boxes stays in memory and is never saved. Your progress — checked items, notes, owner/reviewer, and each check's verdict and trimmed output — is saved to localStorage in this browser so you can resume, and you can remove it any time with Reset or the footer's "Clear local data" action.

Related tools

Other release checklists

What to capture during this OpenAPI compatibility review

Use the checklist as a release note template, not just a pass/fail list. Capture removed paths, changed status codes, narrowed schemas, auth changes, enum changes, and client migration notes. This gives reviewers enough context to understand what changed and what still needs follow-up.

Common blockers

  • Evidence is copied from staging but the production path, host, or namespace is different.
  • A secret, token, cookie, or personal field appears in an example that will be shared outside the team.
  • The release owner signs off without a clear rollback note or known-risk comment.

Helpful next checks