API Documentation
Learn to create comprehensive API documentation using Swagger/OpenAPI
45 min•By Priygop Team•Last updated: Feb 2026
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.
Swagger Implementation
Example
// 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
*/