Introduction to SwaggerHub

The engineering document we’ll use to prototype our API is an OAS document. The advantage of OAS documents is that they’re easy to create and edit. There are also several supporting tools that can read OAS documents and generate things like server-side sample code, API client applications, and human-readable documentation. These are all great shortcuts or prototypes that we can use to validate our design before committing expensive resources to build the production version of our API.

OAS documents have a well-defined structure. An OAS file includes three main sections at the top level:

• The info section holds identifying information such as the title, a brief description, and some additional identifying data.
• The components section is where we’ll place our request and response definitions and other reusable chunks of API specification data.
• The paths section is where we’ll define the exact URLs, response codes, inputs, and outputs for each endpoint of our API.

With that quick overview, let’s start writing up our OAS document for BigCo Inc.’s Onboarding API.

Logging into SwaggerHub

We’ll use the online editor at SwaggerHub to create our OAS file. You can create your OAS documents in any editor, but we’d prefer to use the one at SwaggerHub because it offers lots of syntax help and is also a good place to host a mock version of the API.

To start, visit the landing page for SwaggerHub at https://swagger.io/tools/swaggerhub. If you already have an account, you can just click the “Sign In” button located near the top-right corner of the page. If you’re new to SwaggerHub, click the “Create Free Account” button to create a new account. Creating an account is easy; we can even use our existing GitHub account as our identity at SwaggerHub. This also makes sharing our SwaggerHub content with our GitHub repositories really easy.

Swagger or OpenAPI?: Originally, the specification was known as the Swagger Specification. Nowadays, the proper name is OpenAPI Specification, or OAS. However, lots of the tools associated with OAS still use the name Swagger. We’ll continue to follow this practice here.

Once we’ve logged in, we’ll be forwarded to the “My hub” page. This page shows all the OAS documents associated with both your personal account and any organizations you are a member of, as shown in the following screenshot: