Get Started
The following sections explain important concepts and prerequisites for first-time users.
Read these sections to get started with SwaggerHub Portal.
Prerequisites
You need the following prerequisites to get started with SwaggerHub Portal:
Software as a service (SaaS) enterprise plan with SwaggerHub.
One of the following organization-level roles in the connected SwaggerHub organization:
Designer
Owner
User Personas
Both SwaggerHub Portal and this documentation refer to the following user personas consistently:
Provider. A product designer whose aim is to showcase and promote products.
Consumer. A product user whose aim is to learn what products they can choose from and how to integrate those products into their systems.
SwaggerHub Portal has two distinct views to reflect the user personas. Each view serves a different function:
Provider view. This view lets you build your products and portal landing page.
Consumer view. This is the customer-facing view that showcases the products.
Navigate to SwaggerHub Portal
You have the following options to navigate to SwaggerHub Portal:
In SwaggerHub:
Select the relevant organization.
Select the Go to Portal button.
After your portal has been created, you can use the following URLs:
https://<portal name>.portal.swaggerhub.com/
You can log in to SwaggerHub Portal with SmartBear ID. See the SmartBear ID Documentation to learn about the login process and options.
Trial and Purchase
SwaggerHub Portal is an add-on for SwaggerHub. As such, SwaggerHub Portal cannot be purchased independently. Also, if you wish to stop using SwaggerHub Portal, you can do that without affecting your SwaggerHub plan. In both cases, contact our Sales Team to help you with the process.
A trial period in SwaggerHub Portal is available for new and existing SwaggerHub customers. The SwaggerHub Portal trial period lasts for 14 days.
You can also start your SwaggerHub Portal trial period if you are in the middle of a SwaggerHub trial period. The SwaggerHub Portal trial period also lasts for 14 days in this case.
If you wish to use SwaggerHub Portal after the trial period ends, contact our Sales Team to:
Purchase the product.
Extend the trial period.
Products
A SwaggerHub Portal product contains the following resources:
APIs. One or more API definitions, linked from the respective SwaggerHub organization. APIs are always maintained in SwaggerHub.
Documentation. Pages explaining how to interact with the APIs. Pages are created in Markdown language. The page editor in SwaggerHub Portal features a graphical user interface, also known as a What You See Is What You Get (WYSIWYG) editor.
Product Types
There are the following types of products in SwaggerHub Portal:
Public products. These products are visible to everyone without restrictions. Even users without a SwaggerHub account can view them.
Caution
Public products can contain private APIs. If a public product contains a private API, that private API is visible to everyone even if they are not given specific permissions at the organization or product level in SwaggerHub.
You are responsible for tracking the exposure of private APIs in your public products.
Private products. These products are only visible if you are:
Logged in with SmartBear ID.
A member of the connected SwaggerHub organization with one of the following organization-level or product-level roles:
Consumer
Designer
Owner
See User Management to learn how to set up these roles.
Portal Status
SwaggerHub Portal allows you to set one of the following statuses:
Portal online. This status means that you can access both the provider view and the consumer view. Both providers and consumers can access and navigate your published portal when it is online.
Portal offline. This status means that you can only access the provider view. Opening the consumer view returns an offline message. Providers and consumers cannot access your published portal when it is offline.
You can change the visibility status of your portal anytime.
SwaggerHub Portal Concepts
SwaggerHub Portal uses the following concepts and hierarchy:
A provider or consumer is a member of a SwaggerHub organization.
A SwaggerHub organization can have one associated portal.
A portal contains one or more products.
A product contains:
One or more linked APIs.
One or more documentation pages explaining how to consume the linked API or APIs.
Example Concept Hierarchy for SwaggerHub Portal