Generate an API Changelog from an OpenAPI Spec Diff
When your API spec changes, ask Claude to diff two versions and write a developer-friendly changelog that explains what broke, what changed, and what's new.
# Compare two versions of your spec and generate a changelog
diff openapi-v1.json openapi-v2.json | claude -p "Read this OpenAPI spec diff and write a structured API changelog. Separate breaking changes, new endpoints, deprecated endpoints, and non-breaking schema changes. Use clear developer-friendly language."
Claude identifies the type of each change automatically — a removed field is breaking, an added optional field is not, a renamed endpoint is breaking with a migration path, and so on.
For a detailed migration guide targeting API consumers:
diff openapi-v1.yaml openapi-v2.yaml | claude -p "Generate a migration guide for API consumers upgrading from v1 to v2. For each breaking change, show the before and after, and provide a TypeScript code snippet showing how to update the calling code."
This works especially well in CI — add it to your release pipeline to auto-generate the API changelog section whenever your spec changes:
# In your GitHub Actions workflow
- name: Generate API Changelog
run: |
git diff HEAD~1 HEAD -- openapi.yaml | \
claude -p "Generate an API changelog entry for these spec changes. Format it as a markdown section." \
>> CHANGELOG.md
You can also point Claude at the diff between a feature branch and main before merging:
git diff main -- openapi.yaml | claude -p "Review these API spec changes. Flag any breaking changes or missing deprecation notices before this merges."
Your OpenAPI spec already contains everything needed to write a precise, accurate changelog — Claude just has to read the diff.
Log in to leave a comment.
Set up Claude Code as an automated reviewer in your CI pipeline — on every pull request, it reads the diff, checks for bugs, security issues, missing tests, and convention violations, then posts its findings as a PR comment. Your human reviewers get a head start because the obvious issues are already flagged before they look.
Before deploying, tell Claude to read your project — migrations, environment variables, queue workers, scheduled tasks, caching, third-party integrations — and generate a deployment checklist that's specific to your app. Not a generic "did you run migrations?" list, but one that knows YOUR infrastructure and catches the things YOUR deploy can break.
Instead of writing a README from memory or copying a template, tell Claude to read your project and generate one that's actually accurate — real setup instructions from your config, real architecture from your directory structure, real API examples from your routes, and real prerequisites from your dependency files.