Comparing and Merging API Versions

Last modified on September 17, 2021

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 the Edit permission in the current API.

Compare versions of the same API

  1. Open the API in the SwaggerHub editor.

  2. Switch to one of the versions you want to compare.

  3. Click next to the version to compare with.

    Comparing API versions

Compare with another API on SwaggerHub

  1. Open your API in the SwaggerHub Editor.

  2. If your API has multiple versions, switch to the version you want to compare.

  3. Click the API name. This will open the API Info panel.

    Opening the API Info panel
  4. Click Compare and Merge API in the API Info panel.

    Compare and Merge API
  5. Select Compare with API on SwaggerHub.

    Compare with API on SwaggerHub
  6. Specify the owner, name, and version of the API you want to perform the comparison with.

    Selecting an API to compare with
  7. Click Next to continue to the diff view.

Compare with an external API definition

  1. Open your API in the SwaggerHub Editor.

  2. If your API has multiple versions, switch to the version you want to compare.

  3. Click the API name. This will open the API Info panel.

    Opening the API Info panel
  4. Click Compare and Merge API in the API Info panel.

    Compare and Merge API
  5. Select Compare with external API.

    Compare with external API
  6. 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.

    OpenAPI file URL or path
  7. 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.

OpenAPI diff view

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

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

  2. Click Undo to revert the most recent approval, if needed. To revert several approvals, click Undo several times.

  3. After you merge all the needed differences, click Save Changes to save the changes. This will update the current version with the selected changes.

See Also

APIs
Importing OpenAPI Definitions
Collaboration

Highlight search results