When you feel your API definition is ready for production use, you can publish it. Publishing is a way to show that the API is in a stable state and its endpoints can be reliably called from other applications.
Publishing makes the API definition read-only, so any changes you make after that point should be saved as a new version of the API. Collaborators will not be able to edit the published version either.
Difference between published and unpublished APIs
The difference is mostly semantic:
An unpublished API definition is a draft, a work in progress. Every API in SwaggerHub starts as unpublished. Though unpublished APIs are listed in the SwaggerHub registry, they are not ready for API consumers.
A published API definition is a stable version ready for consuming from client applications. It is not supposed to be changed, and any changes will be introduced as a new version of the API.
Technically, the difference is that published API versions cannot be edited (unless you unpublish them). If you want to change something, you should create a new version of the API and make changes in it.
SwaggerHub shows the Published label next to published APIs and domains. People searching SwaggerHub can also filter the list to show only published APIs.
Published/unpublished vs public/private
Published and unpublished are not the same as public and private. Public and private indicate who can see the API in SwaggerHub -- everyone or just the selected collaborators. Published and unpublished indicate production readiness – whether the API is ready for consumption or not.
Publish an API version
The API owner and collaborators with the Editor role can publish API versions.
Go to the API page in SwaggerHub.
If the API has several versions, select the version you want to publish.
Open the version list and click Publish Version.
(Optional.) Select Set as default version to make this version the default version of your API.
Click Publish Version.
Once published, the API version becomes read-only and cannot be edited. If you need to add new endpoints, change parameters, and so on, you should create a new version of your API and make the changes there. However, if you need to make some important changes to a published API, you can unpublish it temporarily.
|Note:||All collaborators receive an email notification when an API is published or unpublished.|
Unpublish an API version
If you change your mind and want to pull the API definition back to make some changes, you can unpublish the API. To do this, you must be the API owner or a collaborator with the Editor role.
Open the API in the SwaggerHub Editor.
If the API has several versions, switch to the version you want to unpublish.
Open the version list and click Unpublish Version.
In the dialog, click Unpublish Version.
This API version can now be edited again.
Publish and unpublish via CLI
Use SwaggerHub CLI to publish and unpublish your APIs from the command line.
swaggerhub api:publish OWNER/API_NAME/VERSION
Alternatively, you can use the
--publish option of
swaggerhub api:update OWNER/API_NAME/VERSION --file myapi.yaml --publish
swaggerhub api:unpublish OWNER/API_NAME/VERSION
Once you have published your API, you can: