Versioning

All the versions are listed in the dropdown next to the API (domain) name, so you can switch between the versions with just a few clicks.

The API version is also stored in the info.version key in the API definition:

info:
  title: Petstore
  version: 1.0.0

API versions do not depend on each other. They can have different API operations, parameters, descriptions, and so on. The following things are version-specific and are not shared between the versions:

Usually, version numbers look like 1.0.0, but they can actually include any of these characters:

0-9 A-Z a-z . _ - +

Note: A version number must start and end with a digit or letter. The plus (+) character in versions is currently supported in API Hub for Design SaaS only.

Below are examples of valid version numbers:

1
1.0
0.0.1
1.2.3.4
2.4_15
1.0b5
1.2.0-rc3
v1
beta
2016-04-15
2.0.0-SNAPSHOT+20211116

You can choose any versioning scheme, but we recommend semantic versioning, which uses three-part version numbers in the format major.minor.patch.

Anyone with edit access to the API can create and delete versions. This includes the API owner and designers

There are several ways to add a new version to an API or domain.

Option 2

You can change the version in the info section of your API or domain. If you do this, the Save button will change to Create New Version. Click it to save the content as a new version.

Note: This works only for unpublished APIs and domains, because published APIs are read-only and cannot be edited.

If an API or domain uses semantic versioning (major.minor.patch), API Hub for Design Editor displays the versions in descending order, with the latest version on top. Version numbers in other formats are displayed in the order they were created.

The default version is what is shown in search results in API Hub for Design or when someone navigates to your API or domain definition directly without a specific version number, such as https://app.swaggerhub.com/api/swagger-hub/registry-api/. In the editor, the default version is marked with the icon.

To change the default version, click Set as default next to that version:

Additionally, when you create a new version or publish a version, you can set this version as the default one:

You can see who created an API or domain version at the bottom of the Info panel:

Note: The Created By information is only available for the API and domain versions that were created after November 26, 2019. Information about earlier versions can be found in historical audit logs.

There is no direct way to rename versions, but you can use the following workaround:

You can compare two API versions to see how they differ. To do that:

This will open the diff view where you can see the differences between the versions.

You can also compare versions of different APIs, as explained in Comparing and Merging API Versions.

If your API has two or more versions, you can delete the old versions you no longer need. This action cannot be undone. Note that if the API has only one version, you can delete the API instead.

To delete a version, click next to that version in the version list.