how to integrate swagger with my express application

Question

Always I used to share my node side services to some other teams with proper documentation. Based on this documentation, they will use my services.

Regarding this, when I spoke with some other guy. He suggested me to use swagger. But I don't have any idea how to integrate to my application.

My application written in Express. I have did search on this in google, I didn't find any good tutorial. If anyone already implements, can you suggest me. Which module is good and how.

Also just curious to know, are they any other libraries like swagger, which supports Node platform.

Thanks

Marmite

Answer 1

I have experience with documenting an Express API using an express module (swagger-node-express). I also have experience with documenting an Express API using manual Swagger JSON docs.

I would recommend not tying yourself down to a module for your Swagger docs. Most of the modules (and especially swagger-node-express) force you to write your Express code differently to handle the documentation. When manually writing your Swagger docs with JSON, you are able to write Express and decouple the documentation from your routing.

Use Swagger UI to style your documentation and add it to your web page.

Here are some resources you can use when starting out:

Swagger Editor - edit your swagger docs and see your changes live update
Swagger Docs - Swagger specs for JSON
Tutorial - This uses an older version of Swagger, be sure to check out Migrating Swagger to upgrade to the newest version

Also, take a look at this answer explaining the difference between manual and module-based swagger doc generation -> HERE.

Semiprofessional

Answer 2

I have recently come across implementing API documentation using swagger. I have used "swagger-ui-express" npm module to implement it. Created JSON at runtime i.e., once server starts running, I captured data and modified according to the swagger specifications like below file.

https://editor.swagger.io/ Here you can see the swagger specifications in JSON.

Require the "swagger-ui-express" module, create a JSON and feed the file to swaggerui as below.

const swaggerUi = require('swagger-ui-express');
const swaggerDocument = require('./swagger.json');

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));

Northwards

Answer 3

I am not completely clear on what your asking but I think you're looking for something like this: swagger-tools

I use this module and it has been great. It exposes some middleware which you can bind to the Express app that you create. For example, if you have your service documented and that documentation is Swagger compliant, then you can pass that document to the middleware. The middleware does some wonderful things like wiring up request handlers based on the definitions that are found in your documentation and validating requests against definitions found in your documentation.

It has a great tutorial and it is super easy to get setup. I hope this helps and is along the lines of what you were looking for.

Cumuliform

Answer 4

I think you are looking for this:

OpenAPI (Swagger) specification generator for ExpressJS applications

https://github.com/mpashkovskiy/express-oas-generator

To make it work, you need to do the following:

1) Install the library: npm i express-oas-generator —save

2) Integrate with ExpressJS:

const express = require('express')
const expressOasGenerator = require('express-oas-generator')

expressOasGenerator.init(app, {});

3) Open the following URL: http://localhost:3000/api-docs (replace localhost:3000 with your hostname)

It will generate a very nice Swagger output right from the registered routes:

Holden

This saved by day. I was debugging why no routes were being displayed using other libraries and this was a saver. – Janettejaneva

Answer 5

I use swagger like this because it gives me live docs automatically on my express apps:

• API specification: I document my code using OpenAPI (Swagger) specification in YAML format. This is accomplished thanks to swagger-jsdoc.
• Live docs: swagger-ui-express "adds middleware to your express app to serve the Swagger UI bound to your Swagger document. This acts as living documentation for your API hosted from within your app."

Then it's just matter of creating the route where you want your docs to live:

const swaggerSpec = swaggerJSDoc({
  swaggerDefinition: {
    info: {
      title: 'My App API',
      version: '1.0.0'
    }
  },
  apis: ['./routes/index.js']
});

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));

See how swagger-ui-express han built-in support for swagger-jsdoc. Read swagger-ui-express and swagger-jsdocs getting started documentation for more info.

API specification example:

Taken from the swagger-jsdocs getting started documentation.

/**
 * @swagger
 * /login:
 *   post:
 *     description: Login to the application
 *     produces:
 *       - application/json
 *     parameters:
 *       - name: username
 *         description: Username to use for login.
 *         in: formData
 *         required: true
 *         type: string
 *       - name: password
 *         description: User's password.
 *         in: formData
 *         required: true
 *         type: string
 *     responses:
 *       200:
 *         description: login
 */
app.post('/login', function(req, res) {
  res.json(req.body);
});

Generated docs example:

They would look almost like the Swagger UI example.

Member

May I know, How you to separate the authorized API and unauthorized API in Swagger UI with you above procedure? – Cristal

@Win I'd suggest you follow Mike's answer since I've concluded its better that way. With jsons decoupled from the code – Member

Answer 6

Swagger (now OpenAPI) is a popular tool for designing and documenting RESTful APIs. It provides an interactive and user-friendly way to describe your API's endpoints, request parameters, and responses. In this guide, we'll walk through the process of integrating Swagger API documentation into your Node.js project using swagger-jsdoc and swagger-ui-express.

Step-by-Step Integration

1. Install the Required Packages First, you need to install the necessary packages. Open your terminal and run the following commands:

   npm i swagger-jsdoc

   npm i swagger-ui-express

2. Set Up Swagger in Your server.js Next, import the packages and configure Swagger in your main server file (server.js):

   const swaggerJSDoc = require('swagger-jsdoc');

   const swaggerUi = require('swagger-ui-express');

Add the following code to set up Swagger:

// Swagger Code
const options = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: 'API documentation for project',
      version: '1.0.0'
    },
    servers: [
      {
        url: 'http://localhost:3333/'
      }
    ]
  },
  apis: ['./server.js']
}

const swaggerSpec = swaggerJSDoc(options);
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));

This code defines the Swagger specification and serves the documentation at the /api-docs endpoint.

3. Document Your API Endpoints Now, you can add Swagger comments directly in your server.js file to document your API endpoints.

For a GET API:

/**
 * @swagger
 *  /api/users:
 *      get:
 *          summary: Get all users
 *          description: Retrieve a list of all users
 *          responses:
 *              200:
 *                  description: Successfully retrieved list of users
 *                  content:
 *                      application/json:
 *                          schema:
 *                              type: array
 *                              items:
 *                                  type: object
 *                                  properties:
 *                                      id:
 *                                          type: integer
 *                                          description: The user ID
 *                                      name:
 *                                          type: string
 *                                          description: The user's name
 */

For a POST API:

/**
 * @swagger
 *  /route-name:
 *      post:
 *          summary: This is a POST API for action auth
 *          description: For authentication purposes
 *          requestBody:
 *              required: true
 *              content:
 *                  application/json:
 *                      schema:
 *                          type: object
 *                          properties:
 *                              phone_no:
 *                                  type: string
 *                                  description: The user's phone number
 *                              password:
 *                                  type: string
 *                                  description: The user's password
 *                              form_action:
 *                                  type: string
 *                                  description: Form action
 *                          required:
 *                              - phone_no
 *                              - password
 *          responses:
 *              200:
 *                  description: This API is used to fetch data from the database
 *                  content:
 *                      application/json:
 *                          schema:
 *                              type: object
 *                              properties:
 *                                  status:
 *                                      type: boolean
 *                                  message:
 *                                      type: string
 *                                  data:
 *                                      type: object
 */

Replace /route-name with your actual route.

Conclusion Integrating Swagger API documentation into your Node.js project helps streamline API development and improves collaboration. By following these steps, you can easily set up interactive documentation and ensure your API is well-documented and easy to use.

If you have any questions or need further assistance, feel free to reach out!

Hufnagel