Azure DevOps Services Integration
Available in SwaggerHub SaaS, SwaggerHub On-Premise 1.20.0 and later.
The Azure DevOps Services integration lets you synchronize your API definition, auto-generated server code, or client SDK with an existing Git repository in Azure DevOps Services (formerly Visual Studio Team Services or VSTS). Every time you save your API in SwaggerHub, the integration will update the code in the specified repository.
The integration supports both https://dev.azure.com/ORG_NAME and https://ORG_NAME.visualstudio.com accounts.
Supported versions
This integration works with Microsoft’s SaaS platform, Azure DevOps Services. If you use a self-hosted Azure DevOps Server or Team Foundation Server (TFS), use the Azure DevOps Server (TFS Sync) integration instead, which is available in SwaggerHub On-Premise.
The integration supports Git repositories only. Team Foundation Version Control (TFVC) repositories are not supported.
Considerations
This integration supports OpenAPI 2.0 and OpenAPI 3.0.
The target repository must not be empty, it must contain, for example, a README or .gitignore file.
The synchronization is one-way, which means your API definitions go only from SwaggerHub to Azure DevOps Services. You should edit your API definitions in SwaggerHub only.
The integration is bound to a specific version of the API and is not copied when you add a new version. To generate code for different versions, add the integration to each version separately.
Generate an access token
SwaggerHub needs an access token to connect to your Azure DevOps Services instance. To generate this token:
Log in to the Azure DevOps Services web portal as a user who has access to the target repository. This user will be used later to set up the integration. You can use your own account or a service account.
Click your profile photo and select Security.
Select Personal access token.
Click New Token.
Enter a name for this token and select the expiration date.
From the Organization list, select the organization that contains the target repository for the integration, or select All accessible organizations to create a multi-organization access token.
Under Scopes, select Code > Read & write.
Click Create.
Make sure to copy the token to a secure place because you will not see it again.
Important
Keep in mind that the access token has an expiration date. Shortly before the token expires, you will need to update the token in the SwaggerHub integration settings. We recommend that you set a calendar reminder to update the token before it expires.
Configure the integration
To set up or change the Azure DevOps Services integration, you must be the owner of an API.
Follow these steps:
Open your API in the SwaggerHub editor.
If the API has several versions, select the version you want to synchronize with your repository in Azure DevOps Services.
Click the API name to open the API Info panel.
In the API Info panel, switch to the Integrations tab, and click Add New Integrations.
Select Azure DevOps Services from the list of integrations.
Specify the integration parameters:
Name – Required. A display name for the integration.
Organization – The Azure DevOps organization that contains the target repository. You can view a list of your organizations at https://aex.dev.azure.com/me. Enter the organization name without the dev.azure.com or .visualstudio.com part. For example, if your account is dev.azure.com/my-org or my-org.visualstudio.com, enter just my-org.
Note for SwaggerHub On-Premise users: Since v. 1.20.0, you can set the default Azure DevOps organization for integration in the SwaggerHub system configuration. See Configuring Azure DevOps Integrations.
Personal Access Token – The access token that you generated earlier. The token must have the Code (read and write) scope.
Project – Select the team project that contains the target Git repository.
Repository – Select the repository to push the code to. This repository must not be empty. It must contain at least one commit, for example, a README or .gitignore file.
Sync Method – Select the synchronization type:
Sync method
Description
Basic Sync
SwaggerHub will manage all files in the specified branch and folder: new files will be added, existing files will be overwritten, and unused files will be deleted.
Note: In SwaggerHub On-Premise versions up to 1.23.1, Basic Sync always pushes to the branch named SWAGGERHUB. To use a different branch, select Advanced Sync or upgrade your SwaggerHub On-Premise instance to the latest version.
Advanced Sync
Similar to Basic Sync, but you can specify which files will be overwritten or ignored. Use this method if the output folder contains existing files that you want to keep.
Branch – Required. The repository branch to push the code to. If this branch does not exist, it will be created based on the repository’s default branch.
Generated API Code – Required. Select what you want to generate: server code, client SDK, API documentation, or the OpenAPI definition itself as YAML or JSON. See here for a list of supported languages and frameworks.
Tip
To customize code generation options, such as package names, use the Export > Codegen Options menu in the SwaggerHub editor. See Code Generation Options for details.
Output Folder – The output folder for the generated code, relative to the repository root. For example, server or sdk/android. If this folder does not exist, it will be created. If the output folder is not specified, SwaggerHub will create files and folders in the repository root.
Important
Use forward slashes (
/) as path separators:folder/subfolder1/subfolder2 – Correct
folder\subfolder1\subfolder2 – Incorrect
Paths – Available only if you selected Advanced Sync. Use these options to control which files and folders will be created, updated, deleted, or ignored during synchronization. All the paths are relative to the Output Folder. You need to specify either Partially Managed Paths or Fully Managed Paths.
Partially Managed Paths – These files and folders will be created if they do not exist, but the existing files and folders will not be modified. The wildcard
*indicates all files and folders in the Output Folder.Fully Managed Paths – These files and folders will be completely managed by the integration: new files will be added, the existing files will be overwritten, and the files that are no longer used will be deleted. You can use
*as a wildcard for all files.Ignored Paths – These files and folders will remain as is and will not be changed in any way.
Important
Use forward slashes (
/) as path separators, for example, sdk/android/README.md.Output file – Only used if Generated API Code is JSON or YAML, that is, the OpenAPI definition itself. Specifies the name of the .json or .yaml file to create, for example, swagger.yaml or petstore.json. This file will be created in the Output Folder.
Enabled – Keep this check box selected for the integration to work. Unselect it to disable the integration temporarily.
Click Create, then Done.
Push to Azure DevOps Services
When you are ready to push your changes, click Sync on the editor toolbar, enter a commit message and click Push. SwaggerHub will generate the specified target (server code, client code, API documentation or an OpenAPI JSON or YAML file) and push it to the configured repository and branch.
Commits are made on behalf of the user associated with the access token. If synchronization fails (for example, due to a permission problem), you will see an integration error at the top of the SwaggerHub Editor.
Generate multiple targets
You can add multiple instances of the integration for different output targets. For example, one for the ASP.NET server, and another for the C# client. You can even push all the targets to the same repository, but be sure to use different Output Folders to avoid conflicts.
Troubleshooting
Integration fails with an error, or the files are not updated in the repository
Make sure the target repository is not empty. If this is a new repository, commit something to it, for example, a README file.
Make sure the integration user has permissions to push to the target repository and branch. This user must be in the Contributors group or must have explicit Contribute and Create Branch permissions in the repository.
Review the access tokens in Azure DevOps Services and make sure the token used with SwaggerHub is active (not expired or revoked) and has the Code (read and write) scope. If the token has expired, generate a new one, and then delete and re-create the integration in SwaggerHub.
Click the image to enlarge it.
Cannot open the integration settings in SwaggerHub ("Failed to connect to Azure DevOps. Please verify your Personal Access Token.")
This means the access token has expired or was revoked. To resolve the issue:
Delete the existing integration in SwaggerHub.
Re-create the integration using the new access token.
Disable the integration
If you no longer want to sync with Azure DevOps Services, you can disable or delete the integration. The existing files will remain in your repository, but SwaggerHub will not update them anymore.