Generate Comprehensive API Changelogs

API Changelog Generator turns API version differences, specifications, and release notes into structured updates for developers and API consumers. It applies semantic versioning concepts: major releases signal breaking changes, minor releases add backward-compatible features, and patch releases cover fixes and internal improvements. It classifies changes as breaking, deprecated, new, improved, fixed, or security related.

The changelog structure puts breaking changes and required actions first, then organizes new features, other changes, bug fixes, deprecations, and security updates. For each change, it aims to explain developer impact, provide before and after examples, specify migration steps, and state deprecation timelines when known. It can also include related issues, documentation references, deployment schedule, feature flags, SDK changes, performance notes, and rate limit updates.

Use this skill when preparing release documentation for an API version or communicating changes that may affect client integrations. It is useful when comparing OpenAPI specifications or Postman collections, reviewing commits and pull requests, or gathering context from issue trackers and release notes.

Do not invent a breaking change, date, migration step, performance result, security claim, or rate limit from a template. Each entry should be grounded in the actual difference and available release information. Deprecation and rollout timelines should be stated only when confirmed. Security updates should be described without exposing sensitive details.

Inputs can include previous and current API specifications, Postman collections, commit messages, pull requests, issue context, SDK release details, and rollout plans. The output is a developer-focused changelog organized by version and change type. It can include the affected endpoint or feature, what changed, impact, before and after request examples, a migration guide, required client updates, and related documentation.

When comparing specifications, The material names removed endpoints or methods, removed required parameters, changed response schemas, and modified authentication requirements as potential breaking changes. The generator should make the impact legible and prioritize actions developers need to take. It can include migration effort estimates if supporting details exist.

The skill discusses OpenAPI specifications, Postman collections, version control commits and pull requests, issue trackers, API documentation, and JavaScript, Python, and Ruby SDKs. Its automation example uses oapi-diff and changelog-validator in a CI/CD workflow. It does not require a particular repository host or documentation platform.

This skill is for API product teams, technical writers, and developers who need to communicate changes across API versions. It is especially useful when clients need clear migration guidance, when deprecations need a timeline, or when a release spans multiple environments and SDKs. The changelog should be reviewed against the source changes before publication.

oapi-diff previous.yaml current.yaml --format=changelog