Table of Contents

Setting up Swagger hub

  1. Create a free account on https://swagger.io/tools/swaggerhub/
  2. Verify your account and go to your home page: https://app.swaggerhub.com/home

Your first documentation of a GET request

For this exercise, you’ll use the Swagger editor in SwaggerHub to document some simple requests of an API. Let’s say you were writing an OAS file to define an API for a music service. Let’s define two requests: one to retrieve a list of playlists, and another to delete a playlist.

  1. In your home page, click on create API.


  2. Set the openAPI version“ →2.0, Template → None, name → MusicAPI, version → 1.0.0 and Title → Musci API.


  3. Click Create API.
  4. In the editor, an automatically generated template of the OAS file is generated. It contains some metadata about the openAPI version, the API name, its url and base path, and the scheme used. The url is automatically generated by openAPI so that this API can be invoked and tested during documentation.
  5. If you look on the right side, you should see your API documented so far. You’ll see the title, the version, the base url and the scheme.


  6. Let's now define some requests.

Paths and GET Request

  1. The first request to define will return one or more playlists and uses the GET method. Here’s a sample request: GET https://virtserver.swaggerhub.com/Orange-formation/musicAPI/1.0.0/playlist?limit=10&offset=20&search=jazz. This information can be added in the paths section of the OAS file.
  2. Delete the paths: {} entry automatically generated and add the following code to your Swagger editor and click Save: 
    # Endpoints
paths:
  # Playlists
  /playlist:
    # Get one or more playlists
    get:
      # Query parameters
      parameters:
        # Number to return
        - name: limit
          in: query
          required: false
          type: integer
 
        # Number to skip
        - name: offset
          in: query
          required: false
          type: integer
 
        # Search term
        - name: search
          in: query
          required: false
          type: string
  3. The code above defines three query parameters: limit, offset and search as following:

Query parameter Required Definition
limit false Number of playlists to return
offset false Index of the first playlist to return. (0=start at the beginning, 10 = skip the first 10, etc.)
search false Return playlists whose name contains this string

  1. Your API documentation includes now a GET method. If you expand the method, you can see the different parameters. so far.


  2. Let's add the supported response status code with some description for this GET method. Update the get method by adding the responses part as shown below: 
    # Endpoints
paths:
  # Playlists
  /playlist:
    # Get one or more playlists
    get:
      # Query parameters
      parameters:
        # Number to return
        - name: limit
          in: query
          required: false
          type: integer
 
        # Number to skip
        - name: offset
          in: query
          required: false
          type: integer
 
        # Search term
        - name: search
          in: query
          required: false
          type: string
          
      responses:
        # Response code
        200:
          description: Successful response
  3. In the right panel, you can see that information about the response are added to your GET method.


  4. Let's try this API. Click on Try it out. Enter some random values for the query parameters and click Execute.


  5. If the request runs successfully, you should simply see the returned response code 200.