How to Integrate Swagger API Documentation into Your Node.js Project

Gaurang Parante — Wed, 21 Aug 2024 07:46:27 +0000

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!

How to Upload an Excel File in Node.js Using Express and Multer

Gaurang Parante — Sat, 20 Jul 2024 09:16:28 +0000

I'm trying to upload an Excel file in my Node.js application using Express, Multer, and the XLSX library. I've put together the following setup, but I want to ensure I'm doing it correctly and efficiently. Here is my code:

server.js

const express = require('express');
const multer = require('multer');
const xlsx = require('xlsx');
const path = require('path');
const fs = require('fs');

const app = express();

// Serve the HTML file for the upload form
app.get('/', (req, res) => {
    res.sendFile(path.join(__dirname, 'index.html'));
});

// Multer configuration
const storage = multer.diskStorage({
    destination: function (req, file, cb) {
        cb(null, './uploads'); // Uploads directory
    },
    filename: function (req, file, cb) {
        cb(null, file.fieldname + '-' + Date.now() + path.extname(file.originalname));
    }
});

const upload = multer({
    storage: storage,
    fileFilter: function (req, file, cb) {
        const ext = path.extname(file.originalname);
        if (ext !== '.xlsx' && ext !== '.xls') {
            return cb(new Error('Only Excel files are allowed'));
        }
        cb(null, true);
    }
});

// Route to handle file upload
app.post('/upload', upload.single('excel'), (req, res) => {
    try {
        if (!req.file) {
            return res.status(400).send('Please upload an Excel file');
        }

        // Process uploaded file
        const filePath = req.file.path;
        const workbook = xlsx.readFile(filePath);
        const sheetName = workbook.SheetNames[0]; // Assuming it's the first sheet

        // Reading the first sheet
        const worksheet = workbook.Sheets[sheetName];
        const data = xlsx.utils.sheet_to_json(worksheet);
        console.log(data);

        // Redirect to the main page
        res.redirect('/');
    } catch (error) {
        console.error(error);
        res.status(500).send('Error processing file');
    }
});

index.html

<!DOCTYPE html>
<html lang="en">

<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Upload Excel</title>
</head>

<body>
    <h1>Upload Excel File</h1>
    <form action="/upload" method="post" enctype="multipart/form-data">
        <input type="file" name="excel" accept=".xls, .xlsx" required>
        <button type="submit">Upload</button>
    </form>
</body>

</html>

Explanation
Express: Handles HTTP requests and serves static files (index.html).
Multer: Middleware for handling multipart/form-data, used here for file uploads.
XLSX: Library for parsing Excel files.
Path and FS: Node.js modules for handling file paths and system operations.

How It Works:
HTML Form: Provides a form for users to upload Excel files.
Multer Configuration: Sets up Multer to save uploaded files in the ./uploads directory and filter for .xlsx and .xls file types.
File Upload Route: Handles the file upload, reads the Excel file using xlsx.readFile, extracts data from the first sheet, and logs the data to the console.

Questions:
Is this the best way to handle Excel file uploads and processing in Node.js?
Are there any improvements or best practices I should consider for error handling and security?
Any advice or suggestions would be greatly appreciated!

Forem: Gaurang Parante

How to Integrate Swagger API Documentation into Your Node.js Project

How to Upload an Excel File in Node.js Using Express and Multer