Iterative API definition without the chaos

API Definition Managemernt - Versioning

Managing Your API Definitions

More and more tools on the market use the API definition as a starting point. Many people look at the API definition as the ‘source of truth’ for the API. That means you have to manage your definitions carefully, ensuring that you are properly storing and controlling the various versions.


You can have up to 25 versions of your API definition in SwaggerHub. This allows you to continually refine and enhance your definition while still having a clean published version for API consumers to see.

For example, if you are working with collaborators on the next version of your API definition, you might want to create a collaboration version for everyone to work on together while maintaining a solid state version where you can merge the changes you want to incorporate.

API Definition Managemernt - Versioning

There are multiple ways to version your API definition:

  • Save an unpublished definition as another version.
  • Bump a published definition to a new version after you make changes to it (this preserves the published version).
  • Fork to a new API/version altogether.


Speaking of publishing… when you feel your API definition is ready for others to see in the SwaggerHub Registry, you can publish it. Publishing an API definition effectively locks it so any changes you make after that point will be saved as a different version. If you have added collaborators during the course of building that definition, they won’t be able to make any changes to the published version either.

API Definition Publishing

But we know how it is – everybody wants an ‘undo’ button. So we gave you one. If you change your mind and want to pull that API definition back to make some fixes, you can choose to Unpublish it. Unpublishing an API definition removes it from the SwaggerHub registry so you can continue to modify it without all that public scrutiny.

Push to Github

But don’t just store and manage your API definitions in the SwaggerHub registry – we know it’s important to keep your API definitions in your own repository with the rest of your assets. So, after you’ve merged the contributions from your collaborators and you feel you have something ready to commit, use the Push to GitHub option to commit the current version of the API definition to your private or shared repository.


Test faster while improving software quality. Get unlimited access to TestComplete’s Desktop, Mobile & Web modules.

  • 30 Days Free
  • Easy-to-use for all experience levels
  • Access to 500+ real test environments