API Documentation With Swagger in Node.js

API Documentation With Swagger in Node.js

Good API docs make your API usable. Without them, only the author knows how to call it. Here is how to document a Node.js API with Swagger.

What Is Swagger

Swagger (now OpenAPI) is a spec for describing REST APIs. You write a YAML or JSON file describing endpoints, request/response shapes, status codes, and auth. Swagger UI renders it as interactive docs.

Install

npm install swagger-ui-express swagger-jsdoc.

Set Up

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

const options = {
  definition: {
    openapi: '3.0.0',
    info: { title: 'DevTinder API', version: '1.0.0' }
  },
  apis: ['src/routes/*.js']
};

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

Write Docs in JSDoc Comments

/**
 * @openapi
 * /users/{id}:
 *   get:
 *     summary: Get a user by id
 *     parameters:
 *       - in: path
 *         name: id
 *         required: true
 *         schema: { type: string }
 *     responses:
 *       200:
 *         description: A user
 *         content:
 *           application/json:
 *             schema: { $ref: '#/components/schemas/User' }
 *       404:
 *         description: User not found
 */
router.get('/users/:id', getUser);

Why Bother

• Clients can try the API in the browser without writing code.
• Generated client SDKs in many languages from the spec.
• Contract between backend and frontend that lives with the code.
• Onboarding new devs is faster with interactive docs.

Alternatives

• Postman collections: good for sharing with testers.
• Markdown docs: simple but no interactivity.
• Stoplight, Redoc: alternative renderers for OpenAPI.

Keep Docs in Sync

Outdated docs are worse than no docs. Use swagger-jsdoc so the spec lives in JSDoc comments next to the code. When you change a route, you see the doc comment and update it.

The Takeaway

Document your Node.js API with Swagger (OpenAPI). Use swagger-ui-express and swagger-jsdoc. Write specs in JSDoc comments next to the routes so they stay in sync. Visit /docs for interactive API docs. Good docs make your API usable.