Sharing APIs

Last modified on May 22, 2023

This page of the documentation describes sharing in SaaS installations. For working with others in On-Premise installations, click here.

You can easily share your APIs with other individual users and teams on SwaggerHub. The way you share an API depends on whether it is public or private and on the access level (designer or consumer) you want other people to have.

Grant consumer (view) access

The way you do this depends on whether your API is public or private.

Public APIs are visible to anyone on SwaggerHub – both registered users and anonymous viewers. To share your public API with other users, simply copy your API link from the browser’s address bar and send it to your colleagues, partners or customers:

Copying API URL from browser address bar

Viewers do not need a SwaggerHub account to view your public API and do not count towards your plan limits.

 

Private APIs are visible only to the API owner and organization members. To share your private API with other users, you need to add them as consumers or designers. These users need a SwaggerHub account to view your API. The users do not need to be members of your organization, they can be external viewers.

To add users to your private API:

  1. Open your API page on SwaggerHub.

  2. Click the  Share button.

  3. Add the users or teams you want to grant view access to.

The selected users will receive an email with a link to your API. You can also send them the link yourself.

The total number of users you can add depends on your plan.

What Consumer Access Means

Consumers can:

  • View interactive API docs and use the “try it out” functionality.

  • View the YAML code of your API spec and download the spec in the YAML or JSON format.

Granting designer access

To allow other users to edit your API, you need to add them as designers. This applies both to public and private APIs. All designers need a SwaggerHub account. Designers can be members of your organization or they can be external users.

To grant designer access to other users:

  1. Open your API page on SwaggerHub.

  2. Click the  Share button.

  3. In the Collaborate section of the dialog, enter the email addresses of the users you want to grant access to and click the Send Invitations button.

    Granting edit access to an API

The selected users will receive an email with a link to your API. You can also send them the link yourself.

Concurrent editing

Multiple users 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 others.

See Also

Sharing APIs
Public and Private APIs

Highlight search results