Comparing and Merging API Versions

Important

Compare and merge feature is not supported by AsyncAPI or OpenAPI 3.1 specifications.

API Hub for Design has a built-in diff tool that lets you compare and merge API definitions. You can:

Compare versions of the same API.Versioning
Compare an API definition with another API on API Hub for Design or with an external API definition.

Requirements

The API definitions being compared must be valid YAML or JSON.
To use the "compare and merge" tool, you must have the Edit permission in the current API.

Compare versions of the same API

Open the API in the API Hub for Design editor.
Switch to one of the versions you want to compare.
Click next to the version to compare with.

Compare with another API on API Hub for Design

Open your API in the API Hub for Design Editor.
If your API has multiple versions, switch to the version you want to compare.
Click the API name. This will open the API Info panel.
Click in the API Info panel.
Select Compare with API on API Hub for Design.
Click the image to enlarge it.
Specify the owner, name, and version of the API you want to perform the comparison with.
Click the image to enlarge it.
Click Next to continue to the diff view.

Compare with an external API definition

Open your API in the API Hub for Design Editor.
If your API has multiple versions, switch to the version you want to compare.
Click the API name. This will open the API Info panel.
Click in the API Info panel.
Select Compare with external API.
Click the image to enlarge it.
Specify the URL of the YAML or JSON definition you want to perform the comparison with. To upload a file from your computer, click Browse.
Click Fetch to continue.

Diff view

The diff view looks as follows, with the current API version on the right and the other version on the left. Added lines are highlighted in green, modified lines - in blue, removed lines - in red.

Click the image to enlarge it.

The Comparison Type option at the bottom controls what is being compared:

Comparison Type	Description
Design + Metadata	Compare both the design of the API (endpoints, parameters, schemas) and the metadata (descriptions, examples).
Design only	Only compare the design of the API (endpoints, parameters, schemas) while ignoring other metadata like descriptions and examples.

The key order in the definition is not considered a difference, unless you changed the key values or added or deleted some keys.

(Optional) Merge differences

Click the highlighted difference line (or block) in the right or left part of the window. API Hub for Design will copy the block from the left side of the window to the right side (that is, to your API) and will remove highlighting. It will also increase the counter in the Undo button.
Click Undo to revert the most recent approval, if needed. To revert several approvals, click Undo several times.
After you merge all the needed differences, click Save Changes to save the changes. This will update the current version with the selected changes.