Swagger/OpenAPI Generation for JavaScript (Node.js) — Tools and Libraries

Swagger/OpenAPI Generation for JavaScript (Node.js)

When developing a REST API in Node.js, one of the key tasks is creating clear and up-to-date documentation. Swagger (now OpenAPI) has become the de facto standard for describing APIs. In this article, we will review the main tools for automatically generating OpenAPI specifications in JavaScript (Node.js) projects.

What is OpenAPI and why generate it?

OpenAPI is a specification for describing RESTful APIs in JSON or YAML format. It allows you to:

• Automatically create interactive documentation (Swagger UI)
• Generate client SDKs for different languages
• Validate requests and responses
• Simplify integration between teams

Manually writing the specification is a labor-intensive process that quickly becomes outdated. Therefore, tools have been developed for Node.js that generate OpenAPI from code.

Main Tools for OpenAPI Generation in Node.js

1. swagger-jsdoc

The most popular library that parses JSDoc comments in code and converts them into an OpenAPI specification. Install via npm:

npm install swagger-jsdoc swagger-ui-express

Example usage with Express:

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

const options = {  definition: {    openapi: '3.0.0',    info: {      title: 'My API',      version: '1.0.0',      description: 'Example API with documentation generation'    },    servers: [      { url: 'http://localhost:3000' }    ]  },  apis: ['./routes/*.js'] // path to files with annotations};

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

// Example route with annotation/** * @openapi * /users: *   get: *     summary: Get list of users *     tags: [Users] *     responses: *       200: *         description: Successful response *         content: *           application/json: *             schema: *               type: array *               items: *                 $ref: '#/components/schemas/User' */app.get('/users', (req, res) => {  res.json([{ id: 1, name: 'Ivan' }]);});

app.listen(3000);

2. swagger-autogen

A more modern alternative that generates the specification based on annotations in comments and automatically determines data types. Installation:

npm install swagger-autogen

Example generation script:

const swaggerAutogen = require('swagger-autogen')();

const doc = {  info: {    title: 'My API',    description: 'API description'  },  host: 'localhost:3000',  schemes: ['http']};

const outputFile = './swagger-output.json';const endpointsFiles = ['./app.js']; // main file with routes

swaggerAutogen(outputFile, endpointsFiles, doc).then(() => {  require('./app.js'); // start server after generation});

Simply add a comment in the routes:

// #swagger.tags = ['Users']// #swagger.description = 'Endpoint for getting users'app.get('/users', (req, res) => {  // #swagger.responses[200] = { description: 'List of users' }  res.json([{ id: 1, name: 'Anna' }]);});

3. express-oas-generator

A library that intercepts requests and automatically builds an OpenAPI specification based on actual data. Suitable for prototypes:

npm install express-oas-generator

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

expressOasGenerator.init(app, {}); // initialization

app.get('/products', (req, res) => {  res.json