swagger image

Swagger documentation to test Nodejs RestAPIs

We need to test our APIs without frontend, In this blog we are going to see how to test Restful APIs with swagger.

Prerequisites:

  1. Nodejs express initial setup

If you want to know how to setup Nodejs RestAPI with expressjs you can see here

There are so many different ways to test APIs:

  1. Swagger
  2. postman

We can test with postman, it is a very good tool to test the APIs without frontend, the other hand swagger helps us to document and test by creating a interface for the APIs and also we can test with that, its an important asset in the company’s to document the APIs and also to test the API along with it.

How can we add swagger documentation to the APIs

we can document swagger in 2 different ways,

  1. JSON
  2. YAML

we can use any one formats to add documentation for the APIs, Here we will discuss both the format of writing documentation, first we will setup the swagger and give example for the both styles.

you can get complete code from my Github, you can check out here.

Swagger documentaion with JSON format:

STEP1: Install the dependencies

first we need to add the packages required to generate the swagger documenation they are swagger, swagger-jsdoc, swagger-ui-express

Yarn add swagger swagger-jsdoc swagger-ui-express

After installing the dependencies you can see in the package.json like this in the dependencies

swagger js doc packages

if you are using typescript for the backend Nodejs RestAPI, you need to install types for your project, the types for swagger-jsdoc and swagger-ui-express

Yarn add @types/swagger-jsdoc @types/swagger-ui-express

STEP 2: Add configuration to json file

We need to configure the documentation how it should look, we will go set by step

swagger config setup
  1. here first openapi is the swagger documentaion version , you can check the official documentation for that
  2. Next is the info about the API that need to have about the API, here the swagger is more about the documentation of the API, so we need to make sure that none missing in the documentation to look into code,
  3. In components section we add the securityschemas here we can add security to the documenation, in companys it is must, there are different types of securities given to the swagger you can choose based on the usecase

Next we can also add the servers that need to setup and reponse, we can add as many responses as we need, below you can see the url , you can add as many urls as you need

servers add to swagger setup

STEP 3: SetUp the dependencies

  1. import the json file into the main root file
  2. next setup the document to swaggerUI
  3. Here you can see below the line where the path “/api” refers we can see the documentation at that url, you can give your own path as you want.
swagger import to main file

So when you run the application and check the path, you can see like the below image, here you can add routes and schemas as you want

image after running swagger

Swagger documentation with YAML format:

The difference between the json and Yaml format is the file format and another package to support Yaml format,

The basic setup is the same we will convert the same json file into yaml file and configure with the setup

STEP 1: Make a Yaml file for the configuration

We rewrite the config file above in json file to yaml file so you can get good understanding of this,

yaml file config

STEP 2: Install Yamljs :

we need to install yamljs package to help integrating the yaml file with swagger setup

Yarn add yamljs

if you are using typescript you need to add the scripts for yamljs

yarn add @types/yamljs

STEP 3: Add the setup to main root file

yaml setup swagger doc

I just commented out the json file to show the difference, here the difference is to load the YAML file we need to use yamljs package and thats it the rest is same and after this when you run the application you can see the same output as of json.

Conclusion:

Here we have discussed how to install and setup the dependencies for the swagger documentation along with both formats with JSON and YAML for both typescript and javascript.

If you have any comments please write in the comments or reach out to me through contact or any suggestions to improve and anything wrong please write in comments.If you like this content, please share with others

If you want to know how to setup Nodejs RestAPI with expressjs you can see here

About the author

puneethrdy

View all posts