Collaborators are SwaggerHub users who can view or edit your API or domain and who can work on it along with you. For example, if you want to share a private API or domain with other users, you can add these users as collaborators.
The number of collaborators that can be added to an API or domain depends on the SwaggerHub plan of the API or domain owner. In organization-owned APIs and domains, collaborators can be both individual users and teams. Each member of a team counts as one collaborator.
If an API or domain is private, it is accessible only to the owner and collaborators.
If an API or domain is public, anyone can view it, but only the owner and collaborators can change it.
Roles
A user or team can be assigned the following collaborator roles:
- Editor
- Viewer
- Commenter
These roles provide the following privileges, compared to the API or domain owner:
| Privilege | Viewer | Comment 1 | Editor | Owner 2 |
|---|---|---|---|---|
| APIs and Domains | ||||
| View APIs and domains | ✓ | ✓ | ✓ | ✓ |
| Edit APIs and domains | ✓ | ✓ | ||
| Add API and domain versions | ✓ | ✓ | ||
| Delete API and domain versions | ✓ | ✓ | ||
| Publish APIs and domains | ✓ | ✓ | ||
| Unpublish APIs and domains | ✓ | ✓ | ||
| Make APIs and domains public or private | ✓ | ✓ | ||
| Rename APIs and domains | ✓ | ✓ | ||
| Compare and merge APIs and domains | ✓ | ✓ | ||
| Transfer APIs and domains to another owner | ✓ | |||
| Delete APIs and domains | ✓ | |||
| Code generation | ||||
| Generate client and server code 3 | ✓ 3 | ✓ 3 | ✓ 3 | ✓ 3 |
| Configure codegen options | ✓ | ✓ | ||
| Integrations | ||||
| View and trigger integrations | ✓ | ✓ | ||
| Add and manage integrations | ✓ | ✓ | ||
| Collaborators | ||||
| Manage collaborators | ✓ | ✓ | ||
| Comments (OpenAPI only) | ||||
| View comments | ✓ | ✓ | ✓ | |
| Add comments and reply to them | ✓ | ✓ | ✓ | |
| Resolve comments | ✓ 4 | ✓ | ✓ | |
| Edit comments | ✓ 4 | ✓ | ✓ | |
| Delete comments | ✓ 4 | ✓ | ✓ | |
| Reopen resolved comments | ✓ 4 | ✓ | ✓ |
1 Organization members get commenting permissions automatically if the Allow Designers and Consumers to Comment option is enabled for the organization. This option is available in SwaggerHub SaaS, SwaggerHub On-Premise 1.24 and later.
2 In organizations, organization owners are considered to be the owners of the organization’s APIs and domains. Designers who create APIs and domains in the organization get the Editor role.
3 API owners and editors can limit the client and server generators available to individual APIs.
4 Commenters can resolve, edit, delete, and reopen only their own comments.
Add or remove collaborators
The API or domain owner or an editor can add and manage collaborators.
-
Open your API or domain page.
-
In the top right corner, click
:
-
To add collaborators, enter a user name or team name you want to add, and select a role for each collaborator.
Note: Teams can be added only to organization-owned APIs. Each member of a team counts as one collaborator.
To remove a collaborator, click Remove next to their name.
Click the image to enlarge it.
-
Click Save.
Newly invited collaborators will get an email notification.
The number of collaborators you can add to an API or domain depends on your plan or, if the API or domain is owned by an organization, on the organization plan. You can see the limit at the bottom of the dialog shown above.
Email notifications
All collaborators receive an email notification when:
-
They have been added to an API or domain as a collaborator.
-
Comments are added, replied to, resolved or reopened.
-
A version of an API or domain is published, unpublished or deleted.
| Note: | Saving the API in the editor and adding a new API version do not trigger notifications. Also, notifications are not sent to the user who triggered notifications. |
Concurrent editing
You and collaborators can edit the same API definition simultaneously. However, when somebody saves their changes, they can overwrite the changes made by others. To prevent data loss, during editing, SwaggerHub displays a warning every time someone saves their changes to the definition:
Also, if somebody changed the API definition while you were editing it, SwaggerHub will warn you before saving your changes:
To avoid data loss in this case, we recommend that you save your API to a file and then merge it with the API stored in SwaggerHub. You can merge specifications by using the SwaggerHub Compare and Merge feature, or by using some external merge tool.
Also, we recommend that you use comments to coordinate your work with collaborators.