Comparing and Merging API Versions

Important

AsyncAPI does not support the compare and merge feature.

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

Compare versions of the same API.
Compare an API definition with another API on SwaggerHub or with an external API definition.

Requirements

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

Compare versions of the same API

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

Compare with another API on SwaggerHub

Open your API in the SwaggerHub 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 SwaggerHub.
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 SwaggerHub 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 OpenAPI keys and key values.
Design only	Check just the structure, for example, new or deleted OpenAPI keys. The differences in key values are ignored.

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. SwaggerHub 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.