How to document a Node.js API with Swagger

Swagger is an open-source software framework that helps developers design, build, document, and consume RESTful web services. It provides a set of tools that enable developers to describe the structure of APIs in a standard way, making it easier to understand and consume them. Swagger allows developers to create API documentation that is both machine-readable and human-friendly, making it easier to communicate with other developers and stakeholders.

How we can add it to your project?

First of all, this example will use a dummy model, called Publication, which consists of 2 attributes: name and content.

Installation

Make sure you have both swagger-ui-express and swagger-jsdoc installed in your Node.js project:

npm install swagger-ui-express swagger-jsdoc

Configuration

Create a file named app.js and add the following code:

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

const app = express();

// Swagger configuration options
const swaggerOptions = {
  swaggerDefinition: {
    info: {
      title: 'Publication API',
      description: 'CRUD API for managing publications',
      version: '1.0.0',
    },
  },
  apis: ['./routes/*.js'], // Path to the API routes folder
};

const swaggerDocs = swaggerJsDoc(swaggerOptions);
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocs));

// Routes
app.use('/publications', require('./routes/publications'));

// Start the server
app.listen(3000, () => {
  console.log('Server running on port 3000');
});

Documentation

Create a folder named routes in the same directory as app.js. Inside the routes folder, create a file named publications.js and add the following code:

const express = require('express');
const router = express.Router();

/**
 * @swagger
 * /publications:
 *   get:
 *     summary: Get all publications
 *     responses:
 *       200:
 *         description: Returns all publications
 */
router.get('/', (req, res) => {
  // Implementation for getting all publications
});

/**
 * @swagger
 * /publications/{id}:
 *   get:
 *     summary: Get a publication by ID
 *     parameters:
 *       - in: path
 *         name: id
 *         required: true
 *         schema:
 *           type: string
 *         description: Publication ID
 *     responses:
 *       200:
 *         description: Returns the publication with the specified ID
 *       404:
 *         description: Publication not found
 */
router.get('/:id', (req, res) => {
  // Implementation for getting a publication by ID
});

/**
 * @swagger
 * /publications:
 *   post:
 *     summary: Create a new publication
 *     parameters:
 *       - in: body
 *         name: publication
 *         required: true
 *         schema:
 *           type: object
 *           properties:
 *             name:
 *               type: string
 *             content:
 *               type: string
 *         description: Publication object
 *     responses:
 *       201:
 *         description: Publication created successfully
 */
router.post('/', (req, res) => {
  // Implementation for creating a new publication
});

/**
 * @swagger
 * /publications/{id}:
 *   put:
 *     summary: Update a publication by ID
 *     parameters:
 *       - in: path
 *         name: id
 *         required: true
 *         schema:
 *           type: string
 *         description: Publication ID
 *       - in: body
 *         name: publication
 *         required: true
 *         schema:
 *           type: object
 *           properties:
 *             name:
 *               type: string
 *             content:
 *               type: string
 *         description: Updated publication object
 *     responses:
 *       200:
 *         description: Publication updated successfully
 *       404:
 *         description: Publication not found
 */
router.put('/:id', (req, res) => {
  // Implementation for updating a publication by ID
});

/**
 * @swagger
 * /publications/{id}:
 *   delete:
 *     summary: Delete a publication by ID
 *     parameters:
 *       - in: path
 *         name: id
 *         required: true
 *         schema:
 *           type: string
 *         description: Publication ID
 *     responses:
 *       200:
 *         description: Publication deleted successfully
 *       404:
 *         description: Publication not found
 */
router.delete('/:id', (req, res) => {
  // Implementation for deleting a publication by ID
});

module.exports = router;

That’s it! You now have a basic implementation of swagger-ui-express and swagger-jsdoc to document a CRUD API for the "Publication" object. You can start the server by running node app.js, and then access the Swagger UI documentation at http://localhost:3000/api-docs.