Versioning

Last modified on October 20, 2021

SwaggerHub allows you to manage multiple versions of your API or domain definitions. You typically start a new version when you need to add new API operations or parameters, add data models, and so on. Once a new version is ready to be consumed by client applications, you can publish it. This way you can continually enhance your APIs while having a clean published version for your API consumers.

Version list

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

API versions

The API version is also stored in the info.version key in the OpenAPI (Swagger) 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:

Version format

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.

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

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

Add a new version

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

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

Note: When you create a new API version, you can also carry over some existing integrations to the new version.

Option 1

Open the dropdown next to the version number, select Create New Version, then enter a new version number. The new version will contain the same content as the current one.

Create New Version

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.

Create a new version

Version sorting

If an API or domain uses semantic versioning (major.minor.patch), SwaggerHub 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.

Set the default version

The default version is what is shown in search results in SwaggerHub, 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.

Default version

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

Changing the default version

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

Set the default version

See who created a version

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

View who created a version

Note: The Created By information is only available for the API and domain versions that were:

  • created in SwaggerHub SaaS after November 26, 2019,

  • created in SwaggerHub On-Premise 1.23 and later.

Information about earlier versions can be found in historical audit logs.

Rename a version

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

  1. Switch to the version you want to rename.

  2. Create a new version with the desired version number.

  3. Delete the old version.

Compare versions

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

  1. Open your API and select one of the versions you want to compare.

  2. In the version list, click next to the version to compare with.

    Comparing APIs

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.

Delete a version

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.

Note: You can delete only unpublished versions. If a version is published, you need to unpublish it first: select this version, click .

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

Deleting a version

See Also

Creating a New API
Public and Private APIs
Publishing an API
Renaming APIs
Comparing and Merging API Versions

Watch the video
 
Highlight search results