Azure DevOps Server and TFS Integration
Available only in SwaggerHub On-Premise.
The Azure DevOps Server integration (formerly Team Foundation Server Sync) lets you synchronize your API definition, auto-generated server code or client SDK with an existing Git repository in Azure DevOps Server or Team Foundation Server (TFS). Every time you save your API in SwaggerHub, the integration will update the code in the specified repository. You can control which files will be added, updated or ignored in the target repository.
Supported versions
Azure DevOps Server 2019
Team Foundation Server 2017
Git repositories only
The default target server for integration can be specified in your SwaggerHub On-Premise system configuration. See Configuring Azure DevOps Integrations.
Considerations
This integration supports OpenAPI 2.0 and OpenAPI 3.0 (the latter since SwaggerHub On-Premise v. 1.20.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 Server or TFS. 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 Server or TFS instance. To generate this token:
Log in to your Azure DevOps Server or TFS instance (typically http(s)://SERVER/tfs) 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 tokens.
Click Add.
Enter a name for this token and select the expiration date.
Under Selected scopes, select Code (read and write).
Click the image to enlarge it.
Click Create Token.
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 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 Azure DevOps Server or TFS repository.
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 Server from the list of integrations.
Specify the integration parameters:
Name – Required. A display name for the integration.
Azure DevOps Server URL (or TFS URL) – Required. The URL of your Azure DevOps Server or TFS instance, typically http(s)://SERVER/tfs. Use the same value as the Public URL in the Azure DevOps Server (TFS) Administration Console:
Tip
You can set the default server for integration in your SwaggerHub On-Premise 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 Collection – Enter the name of the team project collection that contains the target Git repository. The default one is DefaultCollection.
Click Next to continue. SwaggerHub will validate the access token and display other options.
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 Server
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 Server or TFS 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 Server or TFS, you can disable or delete the integration. The existing files will remain in your repository, but SwaggerHub will not update them anymore.