Change Log
When you publish a version that changes the specification, SelfDocHub compares it with the previous version and stores a Change Log. This page explains what is tracked and where to read it.
What is compared#
Endpoints are matched by operationId when present, otherwise by method and path. So a path change on the same operationId counts as modified, not as removed plus added. The log lists endpoints that were added, removed or modified.
- The very first version of a service has no Change Log.
- Republishing identical content creates none.
- The log is computed when the version is published, not when a page is viewed.
- Deleting a version deletes its Change Log.
- Versions published before Change Log tracking existed have none. An administrator can backfill them. See CLI Reference.
Field-level details#
A modified endpoint carries details for OpenAPI, OpenRPC and GraphQL. Per request parameter and per response field (at any depth, such as items[].price) the log lists what was added, removed or changed, and for a changed item what exactly: type or format (string -> integer), required-ness, enum values, default, deprecation and description. For OpenAPI, fields of responses other than the main success one are prefixed with the code (404: message). Changes of the operation itself (summary, description, deprecation, path) are listed separately.
Breaking changes#
An endpoint is marked Breaking when:
- 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;
- a response field stopped being required or got a new enum value;
- the success response was removed;
- a GraphQL return type changed (except becoming non-null).
Descriptions, deprecation, defaults and error responses are never breaking. AsyncAPI uses direction-aware rules. See AsyncAPI.
Where to read it#
- Versions table. Show Change Log on any version expands the full added/removed/modified list. It is available to every user who can read the page. Each entry links to its endpoint when that endpoint still exists in the current navigation, even from an older version's log.
- Search. The field above the versions table searches all of the service's Change Logs by endpoint name or URI. It uses the same minimum length as the main search, and results are grouped by version.
- Endpoint page. The Change History block shows what changed for that endpoint in every version, with a Breaking mark.
- Exports. The Export Wizard can add a change log to the document. See Export Wizard.
- Notifications. A new version with changes can notify your channels, optionally only for breaking changes. See Notifications.
- MCP. AI clients can read it through
get_version_changelog,search_changeloganddiff_versions. See MCP Server.