Swagger API documentation

Swagger is an open source tool for developers, users and clients to design and document APIs and scale up the project in the organisation.

Problem statement

Usually, one project can have several APIs and every time frontend developer/tester/client needs to connect with the backend developer for
- New API addition and its payload
- Expected response
- Previous API changes
- Which API belongs to which controller or business logic etc

Swagger comes into the picture to avoid this and maintain the bridge between the backend and frontend people.

Steps to Install and integrate with Node Js

1. Run below common in your project terminal

npm i swagger-ui-express

2. Create a swagger.json file

swagger.json file inside the root folder

3. Paste the below code inside swagger.json

{
  "swagger": "2.0",
  "info": {
    "version": "2.0.0",
    "title": "Node Js API validation",
    "description": "API validation along with swagger file",
    "contact": {
      "name": "Akshay Wayanganakr",
      "email": "hi@akshaywayangankar.com",
      "url": "http://akshaywayangankar.com/"
    },
    "license": {
      "name": "MIT",
      "url": "https://opensource.org/licenses/MIT"
    },
    "produces": ["application/json"]
  },
  "host": "localhost:8080",
  "basePath": "/",
  "schemes": ["http"],
  "tags": [
    {
      "name": "User controller",
      "description": "API for users informaton in the application"
    }
  ]
}

You can edit the above information like title, description, contact and tag name according to your project details.

4. Add swagger configuration in your index.js/server.js file

const swagger = require("swagger-ui-express");
const swaggerJson = require("./swagger.json");

And add the below code before API lister

app.use("/api-docs", swagger.serve, swagger.setup(swaggerJson));

swagger configuration

5. Now we are ready to open swagger UI

Type http://localhost:8080/api-docs/#/ (Port will be 8000 by default)

Swagger UI integration

Terms to understand

• Inside the paths object we have to define all routes
• Then the HTML request type whether it is get, post, put or delete
• tags are nothing but the group name
• parameters where we need to pass all payload information
• in is the way we are passing values so it can be body, query, form or path
• response where we can show what expected response should come for API end

How to write routes

1. /get

get method with the help of query as in parameter

"paths": {
  "/getUser": {
    "get": {
      "tags": [
        "User controller"
      ],
      "summary": "Get user info with ID",
      "parameters": [
        {
          "name": "userId",
          "in": "query",
          "description": "Get user info with ID",
          "schema": {
            "properties": {
              "userID": {
                "type": "integer",
                "example": 1
              }
            }
          }
        }
      ],
      "responses": {
        "200": {
          "description": "Successful get api operation"
        },
        "400": {
          "description": "Invalid userId"
        }
      }
    }
  }
}

getUser with a query type parameter

getUser output

You can check this by adding http://localhost:8080/getUser?userId=2 in the browser or inside the postman get method.

And another way to find out the API link is to check in the request URL tab.

curl and request URL tab

Or add curl text inside postman-> import ->Row text and paste copied text over there

postman curl text import

2. /post

http://localhost:8080/deleteUser/userId=4

"/newUser": {
  "post": {
    "tags": [
      "User controller"
    ],
    "summary": "Create new user",
    "parameters": [
      {
        "name": "newUser",
        "in": "body",
        "description": "User that we want to create",
        "schema": {
          "required": [
            "firstName",
            "age",
            "sports"
          ],
          "properties": {
            "firstName": {
              "firstName": "string",
              "example": "Akshay"
            },
            "age": {
              "type": "integer",
              "example": "27"
            },
            "checkBoolean": {
              "type": "boolean",
              "example": true
            },
            "sports": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "example": "Cricket"
                  },
                  "players": {
                    "type": "number",
                    "example": 11
                  }
                }
              }
            },
            "hobbies": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          }
        }
      }
    ],
    "responses": {
      "200": {
        "description": "New user created"
      },
      "400": {
        "description": "Invalid details"
      }
    }
  }
}

newUser with post method and body parameter

response for newUser post method

3. /put

Edit user information with path as in parameter.

http://localhost:8080/editUser/2

"/editUser/{id}": {
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "description": "Edit user information with ID",
      "type": "integer"
    }
  ],
  "put": {
    "tags": [
      "User controller"
    ],
    "summary": "Edit user information with ID",
    "parameters": [
      {
        "name": "editUser",
        "in": "body",
        "description": "edit user information",
        "schema": {
          "$ref": "#/definitions/editUser"
        }
      }
    ],
    "responses": {
      "200": {
        "description": "User data successfully edited",
        "schema": {
          "$ref": "#/definitions/editUser"
        }
      },
      "400": {
        "description": "Wrong inputs to edit information"
      }
    }
  }
}

In this way, we have to declare the definition of editUser schema right after your paths object end

"definitions":{
  "editUser": {
    "required": [
      "name",
      "companies"
    ],
    "properties": {
      "firstName": {
        "type": "string",
        "example": "Akshay"
      },
      "age": {
        "type": "integer",
        "example": "27"
      },
      "checkBoolean": {
        "type": "boolean",
        "example": true
      },
      "sports": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string",
              "example": "Cricket"
            },
            "players": {
              "type": "number",
              "example": 11
            }
          }
        }
      },
      "hobbies": {
        "type": "array",
        "items": {
          "type": "string"
        }
      }
    }
  }
}

put method with path in parameter

response of put method

4. /delete

http://localhost:8080/deleteUser/{id}?userId=4

"/deleteUser/{id}":{
  "delete": {
    "tags": [
      "User controller"
    ],
    "summary": "Delete user information with ID",
    "parameters": [
      {
        "name": "userId",
        "in": "query",
        "description": "Delete user information with ID",
        "schema": {
          "properties": {
            "userID": {
              "type": "integer",
              "example": 1
            }
          }
        }
      }
    ],
    "responses": {
      "200": {
        "description": "User data successfully deleted"
      },
      "400": {
        "description": "Invalid user data for edit"
      }
    }
  }
}

deleteUser with in parameter

deleteUser response

If you want to check the entire swagger code then click on this link and visit my GitHub repository swagger.json file.

Thanks and happy coding 👨‍💻