Generate Comprehensive API Changelogs

This skill provides expertise in creating comprehensive API changelogs that clearly communicate version-to-version changes to developers and API consumers, grounded in semantic versioning, breaking-change classification, and clear entry structure. Semantic versioning compliance defines MAJOR (X.0.0) as breaking changes requiring code modification, MINOR (0.X.0) as backward-compatible new features, and PATCH (0.0.X) as bug fixes and internal improvements. Change classification covers breaking changes (requiring immediate attention and code updates), deprecations (features flagged for future removal with a timeline), new features, improvements, bug fixes, and security updates.

The standard changelog format organizes each version entry into labeled sections: Breaking Changes (each with a migration guide and support-end timeline), New Features (with endpoint/parameter details and example requests), Changes, Bug Fixes, Deprecations (what's deprecated, its replacement, and timeline), and Security. Change detection and documentation covers comparing OpenAPI specifications to detect breaking changes - removed endpoints or methods, removed required parameters, changed response schemas, or modified authentication requirements - for example catching a parameter type change from string to integer, then documenting it with before/after request examples and a concrete migration timeline.

Best practices emphasize clear impact communication (leading with breaking changes and required actions, providing before/after code examples, concrete migration steps, and effort estimates), developer-focused language (concrete new-feature documentation with example requests and JSON responses, e.g. for new pagination support), and version linking (cross-referencing fixed issues, implemented feature requests, and updated documentation pages). Advanced patterns cover multi-environment rollout schedules (staging and regional production dates, feature flags), SDK and client library impact (listing which SDK versions require updating, with before/after code migration examples), and performance/rate-limit changes (documented response-time improvements, memory reductions, and updated rate limits with new header names). Generation guidance covers input handling (comparing API specs like OpenAPI or Postman collections, analyzing commit messages and PRs, reviewing the issue tracker for context, and considering client usage patterns) and output quality (prioritizing changes by developer impact, providing practical migration guidance, including realistic code examples, linking relevant docs, stating deprecation timelines, and highlighting security implications).

Use this skill when releasing a new API version and you need a changelog that clearly separates breaking changes from safe additions, with migration guidance and timelines. It is well suited to APIs following semantic versioning with real breaking-change risk across releases. It is not meant for internal-only changes with no external API consumers, or for a single trivial patch with nothing developer-facing to communicate.

Input: the previous and current API specification (OpenAPI, Postman collection), relevant commits/PRs, and issue tracker context.

Output: a structured API changelog entry with breaking changes, new features, deprecations, and security updates, each with concrete examples and timelines. Example breaking-change entry:

• GET /users/{id}: Parameter id type changed from string to integer
  • Before: GET /api/users/user123
  • After: GET /api/users/123
  • Migration: Update client code to pass numeric user IDs
  • Timeline: String IDs deprecated 2024-01-15, removed 2024-04-15

Compares OpenAPI specifications and Postman collections across versions, and references commit history and issue trackers for change context; it does not connect to a specific API gateway or documentation platform itself.

API teams releasing versioned changes who need clear breaking-change communication and migration guidance, and developer relations teams maintaining changelogs that SDK consumers rely on.