Skip to main content

Lab-4-3

(1.67% of the course mark)

API testing using Swagger​

  • This lab introduces students to API testing using Swagger (OpenAPI) specifications. Learners will use swagger.yaml or swagger.json files to understand, explore, and test RESTful APIs. The focus is on understanding API endpoints, methods, parameters, and responses using tools like Swagger Editor.

Lab objectives​

  • Understand the structure and purpose of swagger.yaml and swagger.json files.

  • Visualize API documentation using Swagger Editor.

  • Identify and explain API endpoints, methods, request parameters, and response formats.

  • Test API endpoints using Swagger Editor.

Express-Api-App Setup​

  1. Download and extract the file Lab-4-3.zip.

  2. Open Visual Studio Code and open the folder of the directory where the folders and files were extracted.

  3. Navigate to: Express-Api-App and create a new folder named: public.

  4. Inside the public folder create file named: swagger.yaml and enter the yaml code below:

openapi: 3.0.3
info:
  title: Users API
  description: API for managing users
  version: 1.0.0

servers:
  - url: http://localhost:3000/api
    description: Production server

paths:
  /users:
    get:
      summary: Get all users
      responses:
        "200":
          description: A list of users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/User"
  /users/{id}:
    get:
      summary: Get a user by id
      parameters:
        - in: path
          name: id
          schema:
            type: integer
          required: true
          description: User id
      responses:
        "200":
          description: A user
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        "404":
          description: User not found

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        firstName:
          type: string
        lastName:
          type: string
  1. Inside the public folder create file named: swagger.json and enter the json code below:
{
  "openapi": "3.0.3",
  "info": {
    "title": "Users API",
    "description": "API for managing users",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "http://localhost:3000/api",
      "description": "Production server"
    }
  ],
  "paths": {
    "/users": {
      "get": {
        "summary": "Get all users",
        "responses": {
          "200": {
            "description": "A list of users",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/User"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/users/{id}": {
      "get": {
        "summary": "Get a user by id",
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "schema": {
              "type": "integer"
            },
            "required": true,
            "description": "User id"
          }
        ],
        "responses": {
          "200": {
            "description": "A user",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/User"
                }
              }
            }
          },
          "404": {
            "description": "User not found"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "User": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "firstName": {
            "type": "string"
          },
          "lastName": {
            "type": "string"
          }
        }
      }
    }
  }
}
tip

Use this link as a guide / explanation on the basic structure of a Swagger file.

  1. Open the terminal and ensure that you are on the root folder of Express-Api-App.

  2. Type the following commands below and press enter.

npm install
npm run start

Swagger Testing​

  1. Navigate to https://editor.swagger.io.

  2. Click on File > Import URL.

  3. Enter http://localhost:3000/public/swagger.yaml and click OK.

  4. You should see something similar to the image below.

swagger-editor

  1. Click on the /user Get all users service.

  2. Click on Try it out then Execute.

  3. Scroll down to view the response. Take a screenshot of the response and name it: get-all-users-yaml.png.

  4. Click on the /users/{id} Get a user by id service.

  5. Click on Try it out and look for the id text box and enter any number from 1 to 10.

swagger-parameter

  1. Click on Execute.

  2. Scroll down to view the response. Take a screenshot of the response and name it: get-a-user-by-id-yaml.png.

  3. Click on File > Import URL.

  4. Enter http://localhost:3000/public/swagger.json and click OK.

  5. Repeat steps 5 - 11 and just name the screenshots get-all-users-json.png and get-a-user-by-id-json.png respectively.

tip

Feel free to experiment with public api's such as {JSON} Placeholder and create a swagger yaml or json file to test the api.

Submission​

  1. Create a folder named submit.

  2. Copy all (get-all-users-yaml.png, get-a-user-by-id--yaml.png, get-all-users-json.png, and get-a-user-by-id-json.png) the previously saved screenshots to this folder.

  3. Create a zip file of this folder.

  4. Navigate back to where the lab was originally downloaded, there should be a Submissions section (see below) where the zip file can be uploaded.

submission