Production and Best Practices: Logging, Monitoring, Documentation, and DeploymentLesson 6.2

API Documentation with OpenAPI and Swagger

OpenAPI specification, Swagger, swagger-jsdoc, swagger-ui-express, API documentation, JSDoc comments, schema definition, interactive documentation

API Documentation with OpenAPI and Swagger

An undocumented REST API is effectively unusable. OpenAPI (formerly Swagger) is the industry standard specification for documenting REST APIs. It defines your API's endpoints, request and response schemas, authentication methods, and error codes in a machine-readable format that generates interactive documentation automatically.

DiagramOpenAPI Documentation Workflow

IMAGE PROMPT (replace this block with your generated image):

Flat hub-and-spoke diagram on white background. Title: OpenAPI Specification Ecosystem. Center: a large rounded rectangle labeled openapi.yaml / openapi.json (the spec file) with fill #3A5EFF and white text. Six spokes radiating outward to six output nodes. Node 1: Browser icon labeled Swagger UI — interactive documentation at /api/docs. Node 2: Postman logo labeled Postman Collection — import spec for testing. Node 3: Code icon labeled Client SDKs — auto-generate in JS, Python, Java. Node 4: Server icon labeled Mock Server — Prism creates mock from spec. Node 5: Shield icon labeled Contract Testing — validate responses against spec. Node 6: CI gear icon labeled CI Validation — lint spec in pipeline. Each spoke arrow in #3A5EFF. Each node is a rounded rectangle with a light #3A5EFF tint background. White background, clean layout.

Setting Up swagger-jsdoc and swagger-ui-express

npm install swagger-jsdoc swagger-ui-express

const options = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: 'My REST API',
      version: '1.0.0',
      description: 'Complete REST API documentation'
    },
    servers: [{ url: 'http://localhost:3000/api' }],
    components: {
      securitySchemes: {
        bearerAuth: { type: 'http', scheme: 'bearer', bearerFormat: 'JWT' }
      }
    }
  },
  apis: ['./src/modules/**/*.routes.js']
};

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

Documenting Endpoints with JSDoc

/**
 * @swagger
 * /users:
 *   get:
 *     summary: Get all users
 *     tags: [Users]
 *     security:
 *       - bearerAuth: []
 *     parameters:
 *       - in: query
 *         name: page
 *         schema:
 *           type: integer
 *           default: 1
 *     responses:
 *       200:
 *         description: List of users
 *       401:
 *         $ref: '#/components/responses/Unauthorized'
 */

Navigate to http://localhost:3000/api/docs to see an interactive UI where you can read documentation and make live API calls. This is the standard documentation experience developers expect from professional APIs.