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.
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.
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:
the contents of the OpenAPI definition,
the public/private and published/unpublished status,
integrations (but you can carry over some integrations when you create a new version),
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 SwaggerHub SaaS only.
Below are examples of valid version numbers:
1 1.0 0.0.1 184.108.40.206 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
Add a new version
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.
|Note:||When you create a new API version, you can also carry over some existing integrations to the new version.|
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.
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), 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.
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:
See who created a version
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 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:
Switch to the version you want to rename.
Create a new version with the desired version number.
Delete the old version.
You can compare two API versions to see how they differ. To do that:
Open your API and select one of the versions you want to compare.
In the version list, click next to the version to compare with.
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:
Creating a New API
Public and Private APIs
Publishing an API
Comparing and Merging API Versions