Collaboration - On-Premise

Last modified on June 01, 2023

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

This page is an introduction to SwaggerHub's access control and sharing for users of On-Premise installations. To perform the steps in this tutorial, you must be an owner of your SwaggerHub account.

Define organizations and teams

SwaggerHub collaborative features were built keeping in mind the needs of the modern team to allow iterative and cross-functional development of APIs. This is possible by defining organizations and teams within SwaggerHub.

To create an organization, click  Create New in the sidebar on the left and select Create New Organization. Specify the Organization Account Name (unique ID), Organization Email, and, optionally, Title.

Create New Organization

Once the organization is successfully created, you can add existing SwaggerHub users as members to the organization. To do that, click in the top right corner of the organization page.

The created organization

Click the image to enlarge it.

This opens the Organization Settings. Switch to the Members tab to invite users to your organization.

Keep in mind that your organization invites will be emailed to team members, and it is up to them to accept the invitation. For example, in the image below, Fernando (fbmattos) has accepted the organization invitation while Daria (daria) has not.

List of organization members

Click the image to enlarge it.

The power of an organization can be fully realized through teams, a feature that lets organization owners group members to collectively work on APIs. In any organization, you can create teams on the Teams tab of the Organization Settings screen:

List of teams

Click the image to enlarge it.

To learn about organizations and teams in detail, check out our documentation.

We have now successfully created an organization, added members, and added them to teams.

Create APIs under your organization

We will be covering how to create an API from scratch under an organization, though it is good to remember that APIs can be imported or forked as well. Check out the Getting Started guide if you are new to creating APIs on SwaggerHub.

Click , select Create New API and choose your organization from the Owner list:

Setting organization as an owner for a new API

Various stakeholders manage different pieces of the development process of an API. Every API starts with understanding the requirements. Is this a private API to be used internally by the company to build better software, or is it a public facing API which could be used to drive the market forward and raise awareness of the company’s products and services?

Depending on the requirements set forth by the product owners and technical leads, the API would identify the need for APIs, be it public or private. SwaggerHub lets owners define the visibility of an API directly in the SwaggerHub Editor:

Making an API private

Private APIs are usually spearheaded by technical leads and development managers that recognize the need for an internal API to ease the development process of other applications within the organization. Product owners, marketing managers and technical leads usually lead the discussion for public APIs which are open to the masses for consumption. It is only when the vision, purpose and technology for the API are fully explored and set, can the API design and development team help make it a reality.

Add collaborators

APIs on SwaggerHub, be it public or private, can have multiple collaborators associated with it. Once the API is created, from the SwaggerHub editor, organization owners can add teams as collaborators to the API with the privileges of their choosing.

The Collaborators dialog

Collaborators can edit the API and communicate with other collaborators via comments. Collaborators can be given the ability to edit the API (Editor), comment on individual lines of the API definition (Commenter) or simply have the ability to view the API (Viewer). Use comments to discuss ideas or point to issues in specific lines of your API definition in the SwaggerHub editor.

See Also

Getting Started
Sharing APIs

Highlight search results