Stacked versions of an API with one change highlighted

API changelog and breaking change detection

Nothing erodes trust in an internal API faster than a field that quietly disappeared. SelfDocHub compares each published version with the previous one and stores the difference, so consumers can see what changed without reading two specs side by side, and the owner can see what they are about to break.

An automatic change log for every version#

When you publish a version that changes the specification, SelfDocHub lists the endpoints that were added, removed or modified. Endpoints are matched by operationId when there is one, otherwise by method and path, so renaming a path of the same operation is a modification, not a removal plus an addition.

For OpenAPI, OpenRPC and GraphQL a modified endpoint carries field-level details: for each request parameter and each response field, at any depth (for example items[].price), what was added, removed or changed, and for a changed item the old and new values. The log is computed at publish time, so reading it is instant.

Breaking changes are flagged for you#

An endpoint is marked Breaking when, for example, a parameter or a field of the main success response was added or removed, a type changed, a parameter became required, an enum value of a parameter was removed or the success response was removed. For GraphQL a changed return type is breaking unless it only becomes non-null. Descriptions, deprecation, defaults and error responses never are. AsyncAPI uses direction-aware rules, because what breaks a publisher differs from what breaks a consumer.

Read it where you work#

  • On the versions table with Show Change Log on any version.
  • On the endpoint page, in a Change History block with the Breaking mark for every version.
  • In the search field above the versions table, which searches all change logs of a service by endpoint name or URI.
  • In an export: the Export Wizard can add the change log to a DOCX, PDF, HTML or Markdown document.
  • Through MCP: AI assistants can call get_version_changelog, search_changelog and diff_versions.

Branches and a personal working version#

Publishing with ?branch=feature-x keeps a separate line of versions, so a pull request can show how the API will look without touching what everybody else reads. A version becomes current automatically only on the service's main branch. Each user can also choose a personal working version to read while the team is mid-migration.

Get told before consumers find out#

Notification rules send a message when a new version with changes is published, optionally only when it contains breaking changes, by webhook, email, Telegram or Slack. Hook that into the channel of the team that owns the consuming services and a breaking change becomes a conversation before the deploy rather than an incident after it.

Keep as much history as you need#

Old versions beyond the configured depth (10 per branch by default) are removed. Administrators and editors can also import a specification file by hand, and anyone who can read a service can export a stored version.

Frequently asked questions

When is the change log calculated?

When a version is published, not when someone opens a page. The first version of a service has no change log, and republishing identical content creates none.

What counts as a breaking change?

For example an added or removed parameter or response field, a changed type, a parameter that became required, a removed enum value or a removed success response. Descriptions, deprecation, defaults and error responses are never breaking.

Can I be notified only about breaking changes?

Yes. A notification rule can fire for every new version with changes or only for breaking ones, through webhook, email, Telegram or Slack.

Run it on your own infrastructure

The Free plan includes a license for one installation. Start with Docker in a few minutes, no credit card needed.