An automatic OpenAPI changelog is only useful if it ignores noise. Reordering paths, reformatting YAML, moving schemas inside the file, or changing comments should not create customer-facing changelog entries.
The changelog should answer a different question:
What changed for a developer integrating with this API?
That is what Sourced's changelog tracking is built around.
What should not count as a changelog item
These changes should usually be ignored:
- key ordering changes
- YAML vs JSON formatting changes
- whitespace
- comments
- path order
- schema order inside
components - generator metadata with no API effect
- description copy changes that do not affect behavior, unless the team chooses to publish them
If a tool creates a changelog item for every moved YAML block, people stop reading the changelog.
What should count
These should become draft changelog candidates:
- endpoint added
- endpoint removed
- method added or removed
- required request property added
- response property removed
- enum value added or removed
- auth requirement changed
- rate-limit behavior documented differently
- error shape changed
- pagination model changed
- SDK method renamed because
operationIdchanged - docs route changed in a way that needs a redirect
The important word is "candidate." Automation can detect likely impact. Humans still approve customer-facing language.
Normalize before diffing
The first rule: never diff raw YAML text.
A good OpenAPI changelog pipeline should:
- Parse the old and new specs.
- Resolve references where needed.
- Sort maps into a stable order.
- Strip non-semantic fields or classify them separately.
- Compare the API model, not the file shape.
- Group changes by operation, schema, auth, and docs impact.
That gives you a semantic diff. A section moving from line 400 to line 40 does not matter. A required field changing from optional to required does.
Approval page, not auto-publish
The right UX is an approval page:
- show detected changelog candidates
- label each as breaking, non-breaking, docs-only, or ignore
- let the team edit titles and customer-facing notes
- allow grouping related changes into one release note
- show linked operation pages and SDK method impact
- require approval before publishing
This is the same principle as SDK publishing. Detection is automated. Customer-facing release communication is approved.
How often should it publish?
Not every OpenAPI change deserves a public post. The cadence should be:
- Immediate: breaking changes, removed endpoints, auth changes, version deprecations.
- Release batch: new endpoints, new optional fields, new examples, new SDK helpers.
- Silent or docs-only: typo fixes, reordered sections, internal description cleanup.
This prevents the changelog from becoming a feed of spec housekeeping.
Example approval workflow
A good approval page might show:
| Candidate | Impact | Default action |
|---|---|---|
POST /invoices added |
non-breaking | publish in release batch |
status enum added paused |
non-breaking but SDK-visible | publish with SDK note |
customer_id became required |
breaking | require approval |
| Paths reordered in YAML | none | ignore |
| Description typo fixed | docs-only | optional |
The reviewer can then add notes like "New paused status only appears for subscription invoices" before publishing.
Why this matters for SDKs
OpenAPI changes are not just docs changes. They change SDK method signatures, generated types, examples, and sometimes package semver.
That is why Sourced pairs changelog candidates with compatibility reports. The changelog tells customers what changed. The compatibility report tells maintainers whether the SDK surface changed in a breaking way.
Try the OpenAPI diff checker or read breaking changes in OpenAPI.