Bitbucket Cloud Sync

This guide is for Bitbucket Cloud (bitbucket.org). If you use self-hosted Bitbucket Server, see Bitbucket Server Sync.

Bitbucket Cloud Sync allows you to synchronize your API definition, auto-generated server code, or client SDK with the specified Git repository in Bitbucket Cloud (bitbucket.org). The synchronization is made every time you save the API in Swagger Studio. You can fully control which files will be added, updated, or ignored in the target repository.

The supported specifications are OpenAPI 2.0, 3.0, and 3.1, and AsyncAPI 2.x and 3.0. Note that the current OpenAPI 3.1 support only includes unresolved resources.

1. Prepare the repository

The target Git repository must not be empty. If it is empty, add at least one file to it, for example, a README or .gitignore file.

2. Create an Atlassian API token (On-Premise only)

Warning

Bitbucket Cloud no longer supports app passwords. In Swagger Studio On-Premise, you can create the integration using your Atlassian account email and an Atlassian API token, but Create and Execute, Push, and Pull currently fail with Unable to clone repository. Synchronization with Bitbucket Cloud is not available in Swagger Studio On-Premise until this is resolved.

Swagger Studio On-Premise connects to Bitbucket Cloud using the email address associated with your Atlassian account and an Atlassian API token. To create the token:

Log in to Atlassian as the user who will authorize the integration. This user must have push access to the target repository. You can use your personal account or a service account created specifically for integration purposes.
Go to id.atlassian.com, open Security, and select API tokens.
Create a new API token with scopes and select Bitbucket as the app.
Select the following scopes:
- read:user:bitbucket
- read:account
- read:me
- read:workspace:bitbucket
- read:repository:bitbucket
- write:repository:bitbucket
Create the token and copy it. This is the only time you can see it.

Note

If the token does not include the read:user:bitbucket scope, the connection fails with 403 Your credentials lack one or more required privilege scopes.

Current behavior in Swagger Studio On-Premise

Create saves the integration without errors. You can reopen and edit it.
Create and Execute also saves the integration, but shows two errors: Create Integration: Unable to clone repository... and Push Failed: Unable to clone repository.... The first message is misleading: the integration is created and appears in the list of integrations.
Clicking Sync, and then Push or Pull, fails with Unable to clone repository. Please verify that authentication provided can access the remote origin at this time.

3. Configure the integration

Open the API in the Swagger Studio editor.
If the API has several versions, select the version whose code you want to store in Bitbucket.
Click the API name to open the API Info panel.
In the info panel, switch to the Integrations tab, and click Add New Integrations:
Select Bitbucket Cloud Sync from the list of integrations.

Specify the integration parameters:

Name – Required. A display name for the integration.
Swagger Studio SaaS – Click Link with Bitbucket and grant access to your Bitbucket Cloud account and repositories.
Username (On-Premise) – The email address of your Atlassian account. Do not use your Bitbucket username; Bitbucket rejects it with a 401: API token must be used with an Atlassian-registered email.
Password (On-Premise) – The Atlassian API token you created in step 2.
Repository Owner – Select the owner of the Bitbucket Cloud repository you want to push the code to.
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	Swagger Studio 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.
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 name of the branch in the repository where your API code will be stored.
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 Swagger Studio 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, Swagger Studio will create files and folders in the repository root.
Important
Use forward slashes (/) as path separators:
folder/subfolder1/subfolder2 – Correct
folder\subfolder1\subfolder2 – Incorrect
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.
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.
Enable – Keep this checkbox selected for the integration to work. Unselect it to temporarily disable the integration.

Click Create, then Done.

Push to Bitbucket Cloud

When you are ready to push your changes, click Sync on the editor toolbar, enter a commit message, and click Push. Swagger Studio 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 Swagger Studio Editor.

Tip: How to generate multiple targets

You can add multiple instances of the integration for different targets. For example, one for the Node.js server and another for the Android client SDK. If you push all the targets to the same repository, use different Output Folders to avoid conflicts.

Disable the integration

If you no longer want to sync with Bitbucket Cloud, you can disable or delete the integration. The existing files will remain in your Bitbucket Cloud repository, but Swagger Studio will not update them anymore.

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.

This can happen if the Atlassian API token (or, in Swagger Studio SaaS, the Bitbucket authorization) used by the integration was revoked or has expired. To resolve the issue:

Create a new API token in Atlassian with the required scopes (On-Premise only).
Delete the existing integration in Swagger Studio.
Add and configure the integration again.