---
name: api-changelog-generator
description: Diff two OpenAPI specs into a human-readable changelog with breaking-change flags, ready for release notes.
title: API Changelog Generator
category: code-development
difficulty: beginner
author: admin
icon: 📜
input: structured-data
output: markdown
phase: post
domain: code
tags: openapi,api-versioning,changelog-generation,breaking-changes,json-schema,diff-detection,release-notes,semantic-versioning,spec-comparison,markdown-output
best_for:
  - API release documentation and breaking-change communication
  - Automated CI/CD changelog pipeline validation
  - OpenAPI/REST service version management
---

## Description

Compares two versions of an OpenAPI / JSON Schema file and produces a categorized changelog: Added, Changed, Deprecated, Breaking. Each entry cites the affected endpoint and field, and breaking changes include a short note on migration steps.

## Why it works

Hand-written API changelogs skew toward shiny new features and under-report breaking changes because the developer remembers the new endpoint but forgets the tightened enum. Mechanical diff ensures breaking changes appear in the release notes — which is what consumers actually need.

## How it works

1. Parse both specs into canonical JSON. 2. Walk the tree and produce per-path, per-method, per-parameter diffs. 3. Apply rules: removed endpoint = breaking; narrowed enum = breaking; widened enum = non-breaking; added required field in request = breaking; removed required field in response = breaking. 4. For each entry, prompt the LLM for a one-sentence human summary using the canonical diff as context. 5. Emit markdown grouped by change category with breaking flagged in bold.