Question 1

What does the API Changelog Generator do?

Accepted Answer

You paste two versions of an API specification — the previous one and the new one — and it computes a precise, categorized changelog by diffing them. It walks both JSON documents recursively, classifies every difference as a breaking change, an addition, or a non-breaking edit, derives the SemVer bump those changes imply, and emits a ready-to-paste Markdown changelog. It accepts OpenAPI-style specs (with a paths map) as well as any plain JSON object, so it works equally well for full specs and individual schema files.

Question 2

How does it decide whether a change is breaking?

Accepted Answer

It applies the rules that actually break consumers. Removing a key — an endpoint, a field, a required entry, an enum value — is breaking, because existing clients may depend on it. Changing a value's type (e.g. integer to number, string to object) is breaking, because deserialization and validation can fail. Adding a new endpoint, field, or optional parameter is treated as a backward-compatible addition. Editing a description or changing a value while keeping the same type is a non-breaking change. Adding a new enum value is non-breaking; removing one is breaking.

Question 3

How does the diff actually work under the hood?

Accepted Answer

It's a real recursive structural diff, not a text diff. Starting from the document roots it compares the two values: if both are objects it unions their keys and recurses into each; if both are arrays it compares index-by-index; if the types differ it records a breaking type change; and if they're primitives of the same type with different values it records a non-breaking value change. Keys present only on the old side are removals, keys present only on the new side are additions. Each change carries its full dotted path (e.g. components.schemas.Order.properties.total) so you can see exactly where it occurred.

Question 4

Does it understand OpenAPI specifically, or just generic JSON?

Accepted Answer

Both. The diff is generic JSON by default, which means it handles any spec shape. On top of that it recognizes the OpenAPI paths map: additions and removals directly under paths are surfaced as 'endpoint added' and 'endpoint removed' rather than anonymous key changes, which is usually the headline of a release. Everything else — components, schemas, parameters, security — is diffed with the same recursive logic.

Question 5

What is the suggested SemVer bump and how is it derived?

Accepted Answer

Semantic Versioning maps directly onto the three change categories: any breaking change requires a MAJOR bump, any backward-compatible addition (with no breaking changes) requires a MINOR bump, and a release with only non-breaking edits is a PATCH. The tool counts each category and applies exactly that precedence — breaking beats added beats changed — then shows the result as a badge. It's a suggestion grounded in the diff, so you can justify the version number to your team or release automation.

Question 6

Is my specification uploaded anywhere?

Accepted Answer

No. Both specs are parsed and diffed entirely in your browser in JavaScript — nothing is sent to a server, there is no account, and there is no telemetry. That makes it safe for internal, pre-release, or proprietary APIs, and it keeps working offline once the page has loaded.

Question 7

Can it produce false positives, and how do I avoid them?

Accepted Answer

Because arrays are compared positionally, reordering items in a list (for example reordering an enum or a parameters array) can register as changes even though the set is unchanged. Likewise, a wholesale reformatting that moves a value's type — a number written as a quoted string in one version — will read as a breaking type change. To get the cleanest changelog, diff the canonical serialized form of each spec (same key style and number formatting) and treat enum/parameter reordering as noise you can ignore in the output.

Question 8

How should I use the output in release notes and migration guides?

Accepted Answer

Copy the generated Markdown straight into your CHANGELOG.md, a GitHub release, or your docs. The breaking-changes section is your migration checklist: each line names the exact path that changed and, for type changes, shows the old and new types so you can describe the upgrade for consumers. Lead your release notes with the breaking section, follow with additions, and keep the non-breaking edits as a 'also changed' footnote.

Question 9

Does it handle deeply nested schemas and large specs?

Accepted Answer

Yes. The diff is fully recursive and runs locally, so it handles deeply nested objects and arrays of objects to any depth, and large specs diff in milliseconds. Every change is reported with its complete path, so even in a thousand-line spec you can locate precisely what moved without scrolling through both files side by side.

Question 10

What if one of my specs isn't valid JSON?

Accepted Answer

Each textarea validates independently and shows a clear parse error with the message from the JSON parser, so you can fix the syntax — a trailing comma or an unquoted key is the usual culprit — and the changelog regenerates live the moment both sides are valid. If your source is YAML, convert it to JSON first; the tool operates on JSON for exact, unambiguous structural comparison.

API Changelog Generator

A diff that knows what actually breaks a client

API Changelog FAQs

Trusted by API & Platform Teams

Related API tools

Similar Calculators

OpenAPI/Swagger Documentation Generator

Postman Collection to Docs Converter

cURL to Documentation Converter

Interactive API Playground Generator

GraphQL Schema Visualizer

Webhook Documentation Generator

Often Used Together

AI Prompt Cost Estimator

Meeting Cost Calculator

Color Contrast Ratio Checker

Package Vulnerability Scanner

Related Articles