Sync API Definitions Between Source Control and SwaggerHub
Available in SwaggerHub SaaS for Enterprise plans and in SwaggerHub On-Premise 1.26 and later.
SwaggerHub integrates with many source control systems allowing you to synchronize your API definitions with an external repository. This integration is bi-directional: you can push changes from SwaggerHub to source control and pull changes from source control to SwaggerHub. This way, your API definitions can be kept in sync regardless of where the changes were made.
Considerations for SwaggerHub SaaS users
Pulling changes from source control is supported only for APIs created in organizations on the Enterprise plan.
If you use a self-hosted source control system, such as GitHub Enterprise Server or Bitbucket Server:
It must be accessible from the public Internet. You may need to allow connections from our IP addresses in your firewall rules.
Its SSL certificate must be issued by a public Certificate Authority (CA). Self-signed and privately signed SSL certificates are not supported.
Note
SwaggerHub On-Premise supports privately-hosted GitHub and Bitbucket servers and self-signed SSL certificates.
Configure integration with source control
To use bi-directional sync, you need to configure a source control integration and specify the repository and branch to synchronize with. For SCM Pull to be enabled, the integration target must be an unresolved JSON or YAML file.
Open the API in SwaggerHub Editor.
If the API has several versions, select the version that you want to sync with source control.
Click the API name, switch to the Integrations tab, and click Add New Integrations:
Select your source control type – GitHub, GitHub Enterprise Server, GitLab, Bitbucket Cloud, Bitbucket Server, Azure DevOps Services, or Azure DevOps Server (SwaggerHub On-Premise only).
Specify the following parameters for the integration. For other available parameters, see the documentation on the GitHub, GitLab, Bitbucket Cloud, Bitbucket Server, Azure DevOps Services, and Azure DevOps Server integrations.
Repository Owner, Repository, and Branch – the repository and branch to synchronize to.
Sync Method – select Basic Sync.
Generated API Code – select JSON (Unresolved) or YAML (Unresolved). This option specifies the format of the API definition file in source control.
Important
Make sure to use the Unresolved option and not Resolved.
Output Folder – the repository folder that contains the API definition file, relative to the repository root. For example,
src/spec. If omitted, SwaggerHub will push to and pull from the repository’s root folder.The folder path is case-sensitive. Use forward slashes
/as path separators. Do not add leading and trailing slashes.folder/subfolder1/subfolder2– Correct\folder\subfolder1\subfolder2\– IncorrectOutput File – The file name, relative to the Output Folder. For example,
openapi.yamlormyapi.json. Case-sensitive.
Click Create, then click Done.
After the integration is set up, you can use the Sync button on the editor toolbar to push to and pull from the connected repository branch.
Push to source control
When you are ready to push your changes, click Sync, enter a commit message, and click Push. SwaggerHub will commit and push the API definition to the connected repository branch. This will completely overwrite the existing file in that branch.
Pull from source control
Any user with Edit permissions on the current API can pull the changes from source control. The API in SwaggerHub must be unpublished (that is, not read-only) in order for pull to work.
To pull the changes, click Sync, then click Pull. The content in the editor will be replaced with the file content from the connected repository branch, with JSON automatically converted to YAML. $ref values are kept as is, that is, external $refs are not resolved.
 |
Click the image to enlarge it.
The changes are pulled as an unsaved draft. Click Save to save the changes, or use the Revert to Last Saved command to undo the pulled changes.
Notes
If the pulled file contains a different
info.versionvalue, SwaggerHub Editor will show the Create New Version button instead of Save. When creating a new API version in SwaggerHub, you can carry over existing source control integrations to the new version. Integrations that were carried over use an auto-generated branch name, so review and update the branch name afterwards if needed.If the API in SwaggerHub is in the OpenAPI 2.0 format and the pulled file is OpenAPI 3.0, SwaggerHub will prompt you to convert the API to OpenAPI 3.0.
To automate the pulling of changes from source control, you can set up a CI/CD process that would upload your API definition to SwaggerHub every time a commit is made in the repository. To upload the file programmatically, you can use the SwaggerHub CLI or Registry API to upload the updated file to SwaggerHub.