API documentation - Swagger & OpenAPI

Perfect — let’s go through API documentation in Node.js using Swagger / OpenAPI, which is essential for well-documented, consumable APIs.

1️⃣ What is Swagger / OpenAPI?

OpenAPI Specification (OAS) = standard format for describing REST APIs
Swagger = set of tools for designing, documenting, and testing APIs
Benefits:
- Auto-generates interactive documentation
- Ensures API consistency
- Facilitates client SDK generation

2️⃣ Installing Swagger in Node.js

npm install swagger-ui-express swagger-jsdoc

swagger-ui-express → serves the UI
swagger-jsdoc → generates docs from JSDoc comments

3️⃣ Basic Setup (Express)

const express = require("express");
const swaggerJsDoc = require("swagger-jsdoc");
const swaggerUi = require("swagger-ui-express");
 
const app = express();
 
// Swagger configuration
const swaggerOptions = {
  swaggerDefinition: {
    openapi: "3.0.0",
    info: {
      title: "My API",
      version: "1.0.0",
      description: "Example Node.js API documentation",
    },
    servers: [{ url: "http://localhost:3000" }],
  },
  apis: ["./routes/*.js"], // files containing annotations
};
 
const swaggerDocs = swaggerJsDoc(swaggerOptions);
app.use("/api-docs", swaggerUi.serve, swaggerUi.setup(swaggerDocs));
 
app.listen(3000, () => console.log("Server running on http://localhost:3000"));

Visit http://localhost:3000/api-docs to see interactive docs

4️⃣ Documenting Endpoints with JSDoc

/**
 * @swagger
 * /users:
 *   get:
 *     summary: Get all users
 *     responses:
 *       200:
 *         description: List of users
 *         content:
 *           application/json:
 *             schema:
 *               type: array
 *               items:
 *                 type: object
 *                 properties:
 *                   id:
 *                     type: integer
 *                   name:
 *                     type: string
 */
app.get("/users", (req, res) => {
  res.json([{ id: 1, name: "Tyson" }]);
});

@swagger comments define endpoint paths, methods, parameters, and responses
Automatically picked up by swagger-jsdoc

5️⃣ Advanced Features

Request parameters: query, path, header
Request body validation: define schemas using application/json
Authentication: JWT, API keys via securitySchemes
Tags: organize endpoints by category

Example:

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer

6️⃣ Benefits of Using Swagger

Interactive documentation → test API in browser
Improved team collaboration → front-end & back-end alignment
Standardized API design → easier maintenance
Client SDK generation → auto-generate client libraries

7️⃣ Key Takeaways

Swagger/OpenAPI = industry standard for REST API documentation
Works with Express, Koa, Fastify
Combines JSDoc annotations + UI for interactive docs
Supports requests, responses, authentication, and schemas

Next, we could go through Logging & Monitoring in Node.js, including Winston, Morgan, and APM tools, which is crucial for production-grade apps.

Do you want to go there next?

Quartz 4

Explorer