API Documentation
Learn to create comprehensive API documentation using Swagger/OpenAPI. This is a foundational concept in server-side JavaScript development that professional developers rely on daily. The explanations below are written to be beginner-friendly while covering the depth and nuance that comes from real-world Node.js experience. Take your time with each section and practice the examples
API Documentation with Swagger
API documentation is essential for developers who will use your API. Swagger/OpenAPI provides a standardized way to document REST APIs with interactive documentation.. This is an essential concept that every Node.js developer must understand thoroughly. In professional development environments, getting this right can mean the difference between code that works reliably and code that breaks in production. The following sections break this down into clear, digestible pieces with practical examples you can try immediately
Swagger Implementation
// Install dependencies
npm install swagger-jsdoc swagger-ui-express
const swaggerJsdoc = require('swagger-jsdoc');
const swaggerUi = require('swagger-ui-express');
// Swagger configuration
const swaggerOptions = {
definition: {
openapi: '3.0.0',
info: {
title: 'User Management API',
version: '1.0.0',
description: 'A RESTful API for managing users',
contact: {
name: 'API Support',
email: 'support@example.com'
}
},
servers: [
{
url: 'http://localhost:3000',
description: 'Development server'
}
],
components: {
securitySchemes: {
bearerAuth: {
type: 'http',
scheme: 'bearer',
bearerFormat: 'JWT'
}
}
}
},
apis: ['./routes/*.js']
};
const specs = swaggerJsdoc(swaggerOptions);
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(specs));
// API documentation with JSDoc comments
/**
* @swagger
* components:
* schemas:
* User:
* type: object
* required:
* - name
* - email
* properties:
* _id:
* type: string
* description: Auto-generated user ID
* name:
* type: string
* description: User's full name
* email:
* type: string
* format: email
* description: User's email address
* age:
* type: integer
* minimum: 0
* maximum: 120
* description: User's age
* createdAt:
* type: string
* format: date-time
* description: User creation timestamp
*/
/**
* @swagger
* /api/users:
* get:
* summary: Get all users
* description: Retrieve a list of all users with pagination
* tags: [Users]
* parameters:
* - in: query
* name: page
* schema:
* type: integer
* default: 1
* description: Page number
* - in: query
* name: limit
* schema:
* type: integer
* default: 10
* description: Number of users per page
* responses:
* 200:
* description: List of users
* content:
* application/json:
* schema:
* type: object
* properties:
* success:
* type: boolean
* data:
* type: array
* items:
* $ref: '#/components/schemas/User'
* pagination:
* type: object
* properties:
* page:
* type: integer
* limit:
* type: integer
* total:
* type: integer
* pages:
* type: integer
* 500:
* description: Server error
*/
/**
* @swagger
* /api/users:
* post:
* summary: Create a new user
* description: Create a new user with the provided information
* tags: [Users]
* requestBody:
* required: true
* content:
* application/json:
* schema:
* type: object
* required:
* - name
* - email
* properties:
* name:
* type: string
* description: User's full name
* email:
* type: string
* format: email
* description: User's email address
* age:
* type: integer
* minimum: 0
* maximum: 120
* description: User's age
* responses:
* 201:
* description: User created successfully
* content:
* application/json:
* schema:
* type: object
* properties:
* success:
* type: boolean
* data:
* $ref: '#/components/schemas/User'
* 400:
* description: Bad request
* 500:
* description: Server error
*/