Swagger and NodeJS integration

API Development for Everyone Swagger allows anyone — be in your development team or your end consumers — to visualize and interact with the API’s resources without having any of the implementation logic in place. It’s automatically generated from your OpenAPI (formerly known as Swagger) Specification, with the visual documentation making it easy for back end implementation and client side consumption.

Requirement

It’s highly recommended to read first these two articles to get full values of this article and also to apply by a real-example

Why swagger?

  • API Design. Swagger makes API design a breeze, with easy-to-use tools for developers, architects, and product owners.

  • API Development. Protocols, error handling, and code modularity are just some of the questions your teams need to address before building a great API. Swagger provides tools for quickly prototyping and building your API’s functionality.

  • API Documentation. Swagger takes the manual work out of API documentation, with a range of solutions for generating, visualizing, and maintaining API docs.

  • API Testing. Swagger tooling and the ReadyAPI platform make it easy to rapidly create, manage, & execute API tests in your pipeline.

  • API Mocking and Virtualization. Reduce dependencies in your development and testing cycles and stand-up realistic, dynamic mocks in seconds.

  • API Governance. People and processes make up a successful API program. Efficiently managing these efforts makes for good governance. Whether you have a team of five or five hundred, Swagger can help.

  • API Monitoring. Monitor API availability, speed, and functionality starting from your OpenAPI Specification (OAS) with AlertSite for OAS. Automate monitor creation and instantly track API behavior to ensure everything runs smoothly in production.

Integration with NodeJS project

In our jwt project install these npm packages npm i swagger-ui-express swagger-jsdoc

  • swagger-ui-express This module allows you to serve auto-generated API docs from express, based on a swagger.json file or jsdoc options . The result is living documentation for your API hosted from your API server via a route.

  • Allows you to markup routes with jsdoc comments. Then produces a full swagger yml config dynamically, which you can pass to this module to produce documentation.

After installing these packages in our server.js file we will add the following code

const swaggerUi = require("swagger-ui-express");
const swaggerJsdoc = require("swagger-jsdoc");
const options = {
  swaggerDefinition: {
    info: {
      title: "JWT authentication & authorization in NodeJS",
      version: "1.0.0",
    },
  },
  apis: ["./src/routes/*"],
};
const swaggerSpecification = swaggerJsdoc(options);
app.use("/api-docs", swaggerUi.serve, swaggerUi.setup(swaggerSpecification));

After that visit this url http://localhost:5000/api-docs/ you will get the following result which means that it’s successfully integrated.

swagger-nodejs-integration

Now We will write the first API documentation in routes/auth.js

  /**
   * @swagger
   * /api/v1/login:
   *    post:
   *        description: This API for authenticate users by typing username and password
   *        consumes:
   *        - application/json
   *        produces:
   *        - application/json
   *        parameters:
   *        - in: body
   *          name: User cerdentials
   *          schema:
   *            $ref: '#/definitions/userCerdentials'
   *        responses:
   *            200:
   *                description: everything is ok
   *            400:
   *                description: bad request
   *            500:
   *                description: internal server error
   * definitions:
   *     userCerdentials:
   *        type: object
   *        required:
   *        - username
   *        - password
   *        properties:
   *            username:
   *                    type: string
   *                    example: ahmed123
   *            password:
   *                    type: string
   *                    example: 1234
   */

Open you browser and visit this URL http://localhost:5000/api-docs you will get this result.

Swagger api doc

Subscribe to our Newsletter

Subscribe to tech-hour website to get all updates, new articles, new courses and projects. No spam ever. Unsubscribe at any time.