Introducing Projects: A Better Way to Organize Your APIs in SwaggerHub

  July 19, 2017

SwaggerHub was created to change the way teams work together on their API development with Swagger (OpenAPI). In addition to bringing together the core capabilities of the open source Swagger tools, SwaggerHub provides a central platform for you to host and manage all of your existing Swagger definitions, and collaborate with your entire team on the design and documentation of your APIs. Since launching the platform, one of the most requested features we’ve heard from SwaggerHub users is the ability to better organize the APIs being worked on across different internal teams. For these teams, SwaggerHub has become the central repository for hosting and discovering all their existing Swagger definitions. As these organizations continued to scale their API development, the need to better organize their API definitions across various teams became increasingly clear. Today, we are excited to announce Projects, a better way to organize your team’s APIs in SwaggerHub.

How Projects Work

Up until today, the best way to organize APIs within SwaggerHub was with Organizations. Organizations allow you to group all of your team members, and the shared APIs, under one single account. The owner of the Organization can easily invite team members to join the Organization, and can manage what level of access each collaborator has to work on the API. But one shortfall to Organizations up to this point, is that each member would have full access to every API definitions, making it a little complicated to manage the growing number of APIs teams are working on. Projects solves that problem — letting Organization owners create special folders called projects, which can contain a select number of your organization’s APIs or Domains (which are reusable components that can be used across multiple APIs to standardize API design), and assign these projects to different members or teams within their Organization.

How Projects Help Improve Your Swagger Workflow

One of the biggest reasons we see API teams making the switch to SwaggerHub from the open source Swagger tools, or commercial third party API development tools, is because it becomes too difficult to keep track of the different API projects that are being worked on by different teams within an organization at any given time. API development is extremely iterative, and going from design to deployment requires input from stakeholders across your software development team. Projects offer an entirely new way to organize your Swagger workflow, and to better manage the people that are involved in helping you build world-class APIs with Swagger.

How to Setup Your First Project in SwaggerHub

To create a project, you need to be an organization owner. Follow these steps:

1. Select Create New > Create a New Project:

2. Name Your Project

On the following screen, specify the organization, to which the project will belong, and enter the project name and arbitrary description (up to 40 characters).

3. Select APIs and Domains

After you created the project, you can add APIs and domains to it. You can do this now, or any time later. To add APIs and domains, click within the Search box and select an API or domain from the drop-down list: To find your API or domain faster, enter any part of its name in the Search box. SwaggerHub will filter the drop-down list on the fly. You can add as many APIs and domains, as needed. If you do not see an API or domain on the list, then, most likely, your organization does not own it. In this case, you can skip this step, and add the API or domain to your project later, after you transfer the API (or domain) ownership to the organization.

4. Invite Members

In this step, you can add users to your project. You can do this now or any time later. To invite users now, click within the Search box and select the desired user from the drop-down list: Note that the list displays only the members of your organization. If you do not see the needed user on the list, you have to add that user to your organization first.

5. Finalize Project Configuration

After you added APIs and domains to the project and invited users, click Save on the Invite Members page. This will save the changes you made to the API and user lists. Read the full documentation for SwaggerHub Projects here. 

Start Organizing Your API Development with Projects

Projects are designed to fit many different use cases for API teams that have a need to maintain and iterate on a large number of APIs. Whether you have different internal teams that need to manage specific API projects, or need a better way to organize all of the different Swagger definitions for the services in your microservice architecture, SwaggerHub can help. Log in now to start your first Project in SwaggerHub. Make sure to let us know how you like the new feature. Shoot us an email [email protected], or click the chat icon in the top of your SwaggerHub dashboard to chat with a member of the team.