Publishing an API
You can publish your API definition when it is ready for production. Publishing is a way to show that the API is stable and that 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. Designers 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 API Hub for Design starts as unpublished. Though unpublished APIs are listed in the API Hub for Design registry, they are not ready for API consumers.
A published API definition is a stable version ready for consumption from client applications. It is not supposed to be changed; any changes will be introduced as a new API version.
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 API version and make changes.
API Hub for Design shows the Published label next to published APIs and domains. People searching API Hub for Design can also filter the State list to show only published APIs.
 |
Click the image to enlarge it.
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 API Hub for Design -- 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 designers can publish API versions.
Go to the API page in API Hub for Design.
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 users sharing an API 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 an Owner or Designer.
Open the API in the API Hub for Design 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 API Hub for Design CLI to publish and unpublish your APIs from the command line.
To publish:
swaggerhub api:publish OWNER/API_NAME/VERSION
To unpublish:
swaggerhub api:unpublish OWNER/API_NAME/VERSION
api:create and api:update also have the --published=publish|unpublish option:
swaggerhub api:update OWNER/API_NAME/VERSION --file myapi.yaml --published=publish
What’s next
Once you have published your API, you can:
Get the link to the API documentation and share it with your API consumers.
Customize the branding of your API documentation.