Collaborators

Last modified on October 20, 2021

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        
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.

  1. Open your API or domain page.

  2. In the top right corner, click :

    Collaboration
  3. 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.

    Collaborators and roles

    Click the image to enlarge it.

  4. 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:

Editing Swagger definitions in SwaggerHub: Warning on concurrent editing

Also, if somebody changed the API definition while you were editing it, SwaggerHub will warn you before saving your changes:

Editing Swagger definitions in SwaggerHub: Message on overwriting 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.

See Also

Comments
Teams

Highlight search results