Basics of SwaggerHub

In the sidebar on the left, click and select Create New API.

Fill in the API information as shown in the image below.

The Specification field specifies the spec format, OpenAPI 3.0.0, OpenAPI 2.0. or AsyncAPI 2.x. Choose OpenAPI 3.0.0.

There are predefined templates, such as Petstore, but now, let’s start with a blank API (no template).

Enter sample as the API name, 1.0.0 as the version, Sample API as the title and an arbitrary description. be sure to change the Auto Mock API slider to the OFF position.

Click Create API. The SwaggerHub editor will open, pre-populated with the API metadata you have entered:

Click the image to enlarge it.

Each API definition starts with the API version, in our example it is openapi: 3.0.0.

openapi: 3.0.0

The next section, info, contains the metadata about the API – the API title, description, version and so on. The info section may also contain contact information, license and other details.

info:
  title: Sample API
  version: 1.0.0
  description: This is a sample API.

The paths section is where you define the API operations. We will populate it later.

paths: {}

Next, we need to define the API server address and the base URL for API calls. Suppose the API will be located at https://api.example.com/v1. This can be described as:

servers:
  - url: https://api.example.com/v1

Add these lines between info and paths, like this:

Suppose our API is intended to manage a list of users. Each user has an ID, and the API needs an operation to return the user by their ID. That would be a GET request like this one:

GET /users/3
GET /users/15

Using Swagger, we can describe this GET operation as follows. The {userId} part in /users/{userId} indicates the path parameter, that is, a URL component that can vary.

paths:
  /users/{userId}:
    get:
      summary: Returns a user by ID
      responses:
        '200':
          description: OK

Paste the code above to the editor, replacing the paths: {} line. Your spec should look like this:

Click the image to enlarge it.

Note that as you edit the spec, SwaggerHub automatically updates the preview on the right.

Our API operation GET /users/{userId} has the userId parameter that specifies the ID of the user to return. To define this parameter in your spec, add the parameter section as follows:

paths:
  /users/{userId}:
    get:
      summary: Returns a user by ID
      parameters:
        - name: userId
          in: path
          required: true
          description: The ID of the user to return
          schema:
            type: integer
      responses:
        '200':
          description: OK

This code specifies the parameter name (the same as the one used in the URL path), type, description and whether it is required. in: path means the parameter is passed as part of the URL path (GET /users/15), as opposed to, say, query string parameters (GET /users?id=15).

Note that after you add the parameters section, the preview is updated to reflect the newly added parameter information:

Click the image to enlarge it.

Next, we need to describe possible responses for the API call. A response is defined by an HTTP status code, description and optional schema (a data model for the response body, if any).

Suppose a successful call to GET /users/{userId} returns HTTP status 200 and this JSON object:

{
  "id": 42,
  "name": "Arthur Dent"
}

To describe this response, add the content section under the 200 response as follows. The content section specifies that the response contains JSON data (application/json). Note the schema element – it describes the structure of the response body, such as the properties of the returned JSON object.

paths: 
  /users/{userId}:
    get:
      ...
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  name:
                    type: string

You can also describe various error codes that can be returned by an API call:

      responses:
        ...
        '400':
          description: The specified user ID is invalid (e.g. not a number)
        '404':
          description: A user with the specified ID was not found

The complete spec should now look like this:

Click the image to enlarge it.

Our API is finished, so let’s publish it. Publishing is a way to tell people that the API is in a stable state, it is going to work as designed and is ready to be consumed by applications. Do not worry about configuring a server – this tutorial is about designing the API specification without actual implementation.

To publish the API, click the drop-down arrow next to your API version, and then click .

Congratulations! You have published your first API on SwaggerHub! You can copy its address from the browser’s address bar and share it with others. Since this is a public API, anyone who has a link can view it, and it will show up in the search results on SwaggerHub. You can make your API private if your SwaggerHub plan allows this.

Note that published APIs become read-only, and can only be edited if the API is unpublished again. It is OK to unpublish an API temporarily if you need to improve the description text or fix typos. But for breaking changes like new operations or parameters, you should start a new version instead by using the Add Version command in the SwaggerHub editor. SwaggerHub lets you maintain multiple versions of an API specification, so you can work on the next API version while keeping the published version (the “production” version) intact.

SwaggerHub editor is not just an editor, it provides tools for managing your API specification and integrating it into your workflow. Let’s take a quick look at other available commands: