+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Home / Tutorials / 📘 typescript
Part 213 of 354

📘 API Documentation: Swagger/OpenAPI

Master api documentation: swagger/openapi in TypeScript with practical examples, best practices, and real-world applications 🚀

🚀Intermediate
25 min read

Prerequisites

  • Basic understanding of JavaScript 📝
  • TypeScript installation ⚡
  • VS Code or preferred IDE 💻

What you'll learn

  • Understand the concept fundamentals 🎯
  • Apply the concept in real projects 🏗️
  • Debug common issues 🐛
  • Write type-safe code ✨

🎯 Introduction

Welcome to this exciting tutorial on API Documentation with Swagger/OpenAPI! 🎉 In this guide, we’ll explore how to document your TypeScript APIs professionally and make them a joy to use.

You’ll discover how Swagger/OpenAPI can transform your API development experience. Whether you’re building REST APIs 🌐, server-side applications 🖥️, or microservices 📚, understanding API documentation is essential for creating robust, maintainable, and user-friendly APIs.

By the end of this tutorial, you’ll feel confident documenting your TypeScript APIs like a pro! Let’s dive in! 🏊‍♂️

📚 Understanding API Documentation

🤔 What is Swagger/OpenAPI?

Swagger/OpenAPI is like a detailed blueprint for your house 🏠. Think of it as a comprehensive manual that tells everyone exactly how to interact with your API - what rooms (endpoints) exist, what furniture (parameters) they contain, and what you can do in each room (operations).

In TypeScript terms, OpenAPI provides a standardized way to describe your API endpoints, request/response models, and authentication methods 📋. This means you can:

  • ✨ Generate interactive documentation automatically
  • 🚀 Create client SDKs in multiple languages
  • 🛡️ Validate requests and responses
  • 🔧 Mock your API for testing

💡 Why Use Swagger/OpenAPI?

Here’s why API developers love Swagger/OpenAPI:

  1. Self-Documenting APIs 📖: Your code becomes the documentation
  2. Interactive Testing 🎮: Test endpoints directly in the browser
  3. Code Generation 🤖: Auto-generate client libraries
  4. Standardization 📏: Follow industry-standard specification
  5. Team Collaboration 🤝: Frontend and backend teams stay in sync

Real-world example: Imagine building a pizza ordering API 🍕. With OpenAPI, you can describe exactly how to order a pizza, what toppings are available, and what the response looks like - all in a format that’s both human and machine readable!

🔧 Basic Syntax and Usage

📝 Simple OpenAPI Specification

Let’s start with a friendly example:

// 👋 Hello, OpenAPI!
import { OpenAPIV3 } from 'openapi-types';

// 🎨 Basic API specification
const apiSpec: OpenAPIV3.Document = {
  openapi: '3.0.0',
  info: {
    title: 'Pizza Palace API 🍕',
    version: '1.0.0',
    description: 'The most delicious API in town!'
  },
  paths: {
    '/pizzas': {
      get: {
        summary: 'Get all pizzas 🍕',
        responses: {
          '200': {
            description: 'List of delicious pizzas',
            content: {
              'application/json': {
                schema: {
                  type: 'array',
                  items: {
                    $ref: '#/components/schemas/Pizza'
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  components: {
    schemas: {
      Pizza: {
        type: 'object',
        properties: {
          id: { type: 'string', example: 'pizza-123' },
          name: { type: 'string', example: 'Margherita Supreme 🍅' },
          price: { type: 'number', example: 15.99 },
          toppings: {
            type: 'array',
            items: { type: 'string' },
            example: ['🍅 Tomato', '🧀 Mozzarella', '🌿 Basil']
          }
        },
        required: ['id', 'name', 'price']
      }
    }
  }
};

💡 Explanation: Notice how we use emojis in our API descriptions to make them more engaging! The $ref creates reusable schemas.

🎯 Express.js with Swagger Integration

Here’s how to integrate with Express.js:

// 🏗️ Express server with Swagger
import express from 'express';
import swaggerJsdoc from 'swagger-jsdoc';
import swaggerUi from 'swagger-ui-express';

const app = express();

// 🎨 Swagger configuration
const swaggerOptions = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: 'My Awesome API 🚀',
      version: '1.0.0',
      description: 'A fantastic TypeScript API!'
    },
    servers: [
      {
        url: 'http://localhost:3000',
        description: 'Development server 🛠️'
      }
    ]
  },
  apis: ['./src/routes/*.ts']
};

// 📚 Generate documentation
const specs = swaggerJsdoc(swaggerOptions);

// 🎮 Serve Swagger UI
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(specs));

// 🔄 Sample route with JSDoc comments
/**
 * @openapi
 * /users:
 *   get:
 *     summary: Get all users 👥
 *     tags: [Users]
 *     responses:
 *       200:
 *         description: List of users
 *         content:
 *           application/json:
 *             schema:
 *               type: array
 *               items:
 *                 $ref: '#/components/schemas/User'
 */
app.get('/users', (req, res) => {
  res.json([
    { id: '1', name: 'Alice 👩', email: '[email protected]' },
    { id: '2', name: 'Bob 👨', email: '[email protected]' }
  ]);
});

💡 Practical Examples

🛒 Example 1: E-commerce API Documentation

Let’s build comprehensive API documentation for an online store:

// 🛍️ E-commerce API types
interface Product {
  id: string;
  name: string;
  price: number;
  category: string;
  inStock: boolean;
  description: string;
  imageUrl: string;
  emoji: string;
}

interface Order {
  id: string;
  userId: string;
  items: OrderItem[];
  total: number;
  status: 'pending' | 'processing' | 'shipped' | 'delivered';
  createdAt: Date;
}

interface OrderItem {
  productId: string;
  quantity: number;
  price: number;
}

// 📝 OpenAPI specification
const ecommerceApiSpec: OpenAPIV3.Document = {
  openapi: '3.0.0',
  info: {
    title: 'ShopMaster API 🛒',
    version: '2.0.0',
    description: 'Your one-stop shop API for all things awesome!',
    contact: {
      name: 'API Support 🤝',
      email: '[email protected]'
    }
  },
  servers: [
    {
      url: 'https://api.shopmaster.com/v2',
      description: 'Production server 🚀'
    },
    {
      url: 'https://staging.shopmaster.com/v2',
      description: 'Staging server 🧪'
    }
  ],
  paths: {
    '/products': {
      get: {
        summary: 'Get all products 🛍️',
        description: 'Retrieve a list of all available products',
        tags: ['Products'],
        parameters: [
          {
            name: 'category',
            in: 'query',
            description: 'Filter by category 🏷️',
            schema: {
              type: 'string',
              enum: ['electronics', 'clothing', 'books', 'home']
            }
          },
          {
            name: 'inStock',
            in: 'query',
            description: 'Filter by stock availability 📦',
            schema: {
              type: 'boolean'
            }
          }
        ],
        responses: {
          '200': {
            description: 'Successful response',
            content: {
              'application/json': {
                schema: {
                  type: 'object',
                  properties: {
                    products: {
                      type: 'array',
                      items: { $ref: '#/components/schemas/Product' }
                    },
                    total: { type: 'number' },
                    page: { type: 'number' }
                  }
                }
              }
            }
          },
          '400': {
            description: 'Invalid query parameters',
            content: {
              'application/json': {
                schema: { $ref: '#/components/schemas/Error' }
              }
            }
          }
        }
      },
      post: {
        summary: 'Create a new product ➕',
        description: 'Add a new product to the inventory',
        tags: ['Products'],
        security: [{ bearerAuth: [] }],
        requestBody: {
          required: true,
          content: {
            'application/json': {
              schema: { $ref: '#/components/schemas/ProductInput' }
            }
          }
        },
        responses: {
          '201': {
            description: 'Product created successfully 🎉',
            content: {
              'application/json': {
                schema: { $ref: '#/components/schemas/Product' }
              }
            }
          },
          '400': {
            description: 'Invalid product data',
            content: {
              'application/json': {
                schema: { $ref: '#/components/schemas/Error' }
              }
            }
          },
          '401': {
            description: 'Unauthorized - Admin access required 🔒'
          }
        }
      }
    },
    '/orders': {
      post: {
        summary: 'Create a new order 📦',
        description: 'Place a new order with multiple items',
        tags: ['Orders'],
        security: [{ bearerAuth: [] }],
        requestBody: {
          required: true,
          content: {
            'application/json': {
              schema: { $ref: '#/components/schemas/OrderInput' }
            }
          }
        },
        responses: {
          '201': {
            description: 'Order created successfully 🎊',
            content: {
              'application/json': {
                schema: { $ref: '#/components/schemas/Order' }
              }
            }
          }
        }
      }
    }
  },
  components: {
    schemas: {
      Product: {
        type: 'object',
        properties: {
          id: { type: 'string', example: 'prod-123' },
          name: { type: 'string', example: 'Wireless Headphones 🎧' },
          price: { type: 'number', format: 'float', example: 99.99 },
          category: { 
            type: 'string', 
            enum: ['electronics', 'clothing', 'books', 'home'],
            example: 'electronics'
          },
          inStock: { type: 'boolean', example: true },
          description: { 
            type: 'string', 
            example: 'Amazing wireless headphones with noise cancellation'
          },
          imageUrl: { 
            type: 'string', 
            format: 'uri',
            example: 'https://example.com/headphones.jpg'
          },
          emoji: { type: 'string', example: '🎧' }
        },
        required: ['id', 'name', 'price', 'category', 'inStock']
      },
      ProductInput: {
        type: 'object',
        properties: {
          name: { type: 'string', minLength: 1 },
          price: { type: 'number', minimum: 0 },
          category: { 
            type: 'string', 
            enum: ['electronics', 'clothing', 'books', 'home']
          },
          description: { type: 'string' },
          imageUrl: { type: 'string', format: 'uri' },
          emoji: { type: 'string', maxLength: 2 }
        },
        required: ['name', 'price', 'category']
      },
      Order: {
        type: 'object',
        properties: {
          id: { type: 'string', example: 'order-456' },
          userId: { type: 'string', example: 'user-789' },
          items: {
            type: 'array',
            items: { $ref: '#/components/schemas/OrderItem' }
          },
          total: { type: 'number', format: 'float', example: 199.98 },
          status: {
            type: 'string',
            enum: ['pending', 'processing', 'shipped', 'delivered'],
            example: 'pending'
          },
          createdAt: { 
            type: 'string', 
            format: 'date-time',
            example: '2024-01-15T10:30:00Z'
          }
        }
      },
      OrderItem: {
        type: 'object',
        properties: {
          productId: { type: 'string', example: 'prod-123' },
          quantity: { type: 'integer', minimum: 1, example: 2 },
          price: { type: 'number', format: 'float', example: 99.99 }
        },
        required: ['productId', 'quantity', 'price']
      },
      OrderInput: {
        type: 'object',
        properties: {
          items: {
            type: 'array',
            items: {
              type: 'object',
              properties: {
                productId: { type: 'string' },
                quantity: { type: 'integer', minimum: 1 }
              },
              required: ['productId', 'quantity']
            }
          }
        },
        required: ['items']
      },
      Error: {
        type: 'object',
        properties: {
          code: { type: 'string', example: 'INVALID_INPUT' },
          message: { type: 'string', example: 'The provided data is invalid' },
          details: { type: 'array', items: { type: 'string' } }
        }
      }
    },
    securitySchemes: {
      bearerAuth: {
        type: 'http',
        scheme: 'bearer',
        bearerFormat: 'JWT',
        description: 'Enter your JWT token 🔑'
      }
    }
  }
};

🎯 Try it yourself: Add an endpoint for getting order history and include pagination parameters!

🎮 Example 2: Gaming API with Advanced Features

Let’s create documentation for a gaming leaderboard API:

// 🏆 Gaming API with decorators
import { ApiProperty, ApiResponse, ApiTags } from '@nestjs/swagger';

@ApiTags('🎮 Players')
export class PlayerDto {
  @ApiProperty({ 
    description: 'Unique player identifier',
    example: 'player-007'
  })
  id: string;

  @ApiProperty({ 
    description: 'Player username with emoji',
    example: 'GamerPro 🎯'
  })
  username: string;

  @ApiProperty({ 
    description: 'Player level',
    minimum: 1,
    maximum: 100,
    example: 42
  })
  level: number;

  @ApiProperty({ 
    description: 'Total experience points',
    example: 12500
  })
  xp: number;

  @ApiProperty({ 
    description: 'Player achievements',
    type: [String],
    example: ['🏆 First Victory', '🔥 Streak Master', '💎 Diamond Rank']
  })
  achievements: string[];

  @ApiProperty({ 
    description: 'Online status',
    enum: ['online', 'offline', 'away'],
    example: 'online'
  })
  status: 'online' | 'offline' | 'away';
}

@ApiTags('🏆 Leaderboard')
export class LeaderboardController {
  @ApiResponse({
    status: 200,
    description: 'Top players retrieved successfully 🎊',
    type: [PlayerDto]
  })
  @ApiResponse({
    status: 429,
    description: 'Rate limit exceeded ⏰'
  })
  async getTopPlayers(): Promise<PlayerDto[]> {
    return [
      {
        id: 'player-001',
        username: 'ProGamer 🎯',
        level: 95,
        xp: 89750,
        achievements: ['🏆 Champion', '🔥 Unstoppable', '💎 Legend'],
        status: 'online'
      },
      {
        id: 'player-002',
        username: 'SpeedRunner ⚡',
        level: 87,
        xp: 76230,
        achievements: ['🏃 Speed Demon', '⏱️ Time Master'],
        status: 'away'
      }
    ];
  }
}

🚀 Advanced Concepts

🧙‍♂️ Advanced Topic 1: Custom Validation and Schemas

When you’re ready to level up, try advanced schema validation:

// 🎯 Advanced schema with custom validation
const advancedSchema: OpenAPIV3.SchemaObject = {
  type: 'object',
  properties: {
    email: {
      type: 'string',
      format: 'email',
      pattern: '^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$',
      example: '[email protected]'
    },
    age: {
      type: 'integer',
      minimum: 13,
      maximum: 120,
      example: 25
    },
    preferences: {
      type: 'object',
      properties: {
        theme: {
          type: 'string',
          enum: ['light', 'dark', 'auto'],
          default: 'auto'
        },
        notifications: {
          type: 'object',
          properties: {
            email: { type: 'boolean', default: true },
            push: { type: 'boolean', default: false },
            sms: { type: 'boolean', default: false }
          },
          additionalProperties: false
        }
      }
    }
  },
  required: ['email', 'age'],
  additionalProperties: false
};

// 🪄 Conditional schemas based on discriminator
const paymentMethodSchema: OpenAPIV3.SchemaObject = {
  oneOf: [
    {
      type: 'object',
      properties: {
        type: { type: 'string', enum: ['credit_card'] },
        cardNumber: { type: 'string', pattern: '^[0-9]{16}$' },
        expiryDate: { type: 'string', pattern: '^(0[1-9]|1[0-2])\/[0-9]{2}$' },
        cvv: { type: 'string', pattern: '^[0-9]{3,4}$' }
      },
      required: ['type', 'cardNumber', 'expiryDate', 'cvv']
    },
    {
      type: 'object',
      properties: {
        type: { type: 'string', enum: ['paypal'] },
        email: { type: 'string', format: 'email' }
      },
      required: ['type', 'email']
    }
  ],
  discriminator: {
    propertyName: 'type'
  }
};

🏗️ Advanced Topic 2: Code Generation and Automation

For the brave developers who want to automate everything:

// 🚀 Automated client generation
import { generateApi } from 'swagger-typescript-api';

const generateClient = async () => {
  const { files } = await generateApi({
    name: 'MyApi.ts',
    url: 'http://localhost:3000/api-docs-json',
    generateClient: true,
    generateRouteTypes: true,
    generateResponses: true,
    toJS: false,
    extractRequestParams: true,
    extractRequestBody: true,
    extractEnums: true,
    prettier: {
      printWidth: 120,
      tabWidth: 2,
      trailingComma: 'all',
      singleQuote: true
    }
  });

  console.log('🎉 Generated client files:', files);
};

// 🔧 Custom code generation with templates
const customTemplate = `
// 🎨 Auto-generated API client
export class {{className}}Api {
  constructor(private baseUrl: string) {}

  {{#operations}}
  async {{operationId}}({{#parameters}}{{paramName}}: {{dataType}}{{#hasMore}}, {{/hasMore}}{{/parameters}}): Promise<{{returnType}}> {
    const response = await fetch(\`\${this.baseUrl}{{path}}\`, {
      method: '{{httpMethod}}',
      headers: {
        'Content-Type': 'application/json',
        {{#hasAuth}}'Authorization': \`Bearer \${this.token}\`{{/hasAuth}}
      },
      {{#hasBody}}body: JSON.stringify({{bodyParam}}){{/hasBody}}
    });
    
    if (!response.ok) {
      throw new Error(\`HTTP \${response.status}: \${response.statusText}\`);
    }
    
    return response.json();
  }
  {{/operations}}
}
`;

⚠️ Common Pitfalls and Solutions

😱 Pitfall 1: Inconsistent Documentation

// ❌ Wrong way - outdated documentation!
/**
 * @openapi
 * /users:
 *   get:
 *     summary: Get all users
 *     responses:
 *       200:
 *         description: List of users
 *         content:
 *           application/json:
 *             schema:
 *               type: array
 *               items:
 *                 type: object
 *                 properties:
 *                   id: { type: string }
 *                   name: { type: string }
 */
app.get('/users', (req, res) => {
  // 💥 Actual response has different structure!
  res.json([
    { 
      userId: '1', 
      fullName: 'Alice', 
      email: '[email protected]',
      createdAt: new Date()
    }
  ]);
});

// ✅ Correct way - keep docs in sync!
/**
 * @openapi
 * /users:
 *   get:
 *     summary: Get all users 👥
 *     responses:
 *       200:
 *         description: List of users
 *         content:
 *           application/json:
 *             schema:
 *               type: array
 *               items:
 *                 $ref: '#/components/schemas/User'
 * components:
 *   schemas:
 *     User:
 *       type: object
 *       properties:
 *         userId: { type: string, example: "user-123" }
 *         fullName: { type: string, example: "Alice Wonder" }
 *         email: { type: string, format: email }
 *         createdAt: { type: string, format: date-time }
 */
app.get('/users', (req, res) => {
  res.json([
    {
      userId: 'user-123',
      fullName: 'Alice Wonder',
      email: '[email protected]',
      createdAt: new Date().toISOString()
    }
  ]);
});

🤯 Pitfall 2: Missing Error Responses

// ❌ Dangerous - no error documentation!
/**
 * @openapi
 * /users/{id}:
 *   get:
 *     summary: Get user by ID
 *     responses:
 *       200:
 *         description: User found
 */
app.get('/users/:id', (req, res) => {
  // 💥 What if user not found? No documentation!
  const user = findUserById(req.params.id);
  if (!user) {
    return res.status(404).json({ error: 'User not found' });
  }
  res.json(user);
});

// ✅ Safe - document all possible responses!
/**
 * @openapi
 * /users/{id}:
 *   get:
 *     summary: Get user by ID 🔍
 *     parameters:
 *       - in: path
 *         name: id
 *         required: true
 *         schema:
 *           type: string
 *         description: User identifier
 *     responses:
 *       200:
 *         description: User found successfully ✅
 *         content:
 *           application/json:
 *             schema:
 *               $ref: '#/components/schemas/User'
 *       404:
 *         description: User not found ❌
 *         content:
 *           application/json:
 *             schema:
 *               $ref: '#/components/schemas/Error'
 *       400:
 *         description: Invalid user ID format ⚠️
 */
app.get('/users/:id', (req, res) => {
  const { id } = req.params;
  
  if (!isValidId(id)) {
    return res.status(400).json({
      error: 'INVALID_ID',
      message: 'User ID must be a valid format'
    });
  }
  
  const user = findUserById(id);
  if (!user) {
    return res.status(404).json({
      error: 'USER_NOT_FOUND',
      message: 'No user found with the specified ID'
    });
  }
  
  res.json(user);
});

🛠️ Best Practices

  1. 🎯 Keep Documentation Updated: Use automation to sync docs with code
  2. 📝 Write Descriptive Summaries: Make each endpoint’s purpose clear
  3. 🛡️ Document Error Cases: Include all possible error responses
  4. 🎨 Use Examples Liberally: Show real data in your examples
  5. ✨ Version Your API: Use semantic versioning for API changes
  6. 🔧 Validate Your Spec: Use OpenAPI validators
  7. 🚀 Generate Clients: Automate client library generation
  8. 📊 Monitor Usage: Track which endpoints are actually used

🧪 Hands-On Exercise

🎯 Challenge: Build a Complete Movie Database API Documentation

Create comprehensive API documentation for a movie database:

📋 Requirements:

  • ✅ Movie CRUD operations (Create, Read, Update, Delete)
  • 🎬 Movie search with filters (genre, year, rating)
  • 👤 User authentication and authorization
  • ⭐ Movie rating and review system
  • 📊 Statistics endpoint for admin users
  • 🎨 Use fun movie-themed examples with emojis!

🚀 Bonus Points:

  • Add pagination for large result sets
  • Include file upload for movie posters
  • Create webhook endpoints for real-time updates
  • Add rate limiting documentation

💡 Solution

🔍 Click to see solution
// 🎯 Complete Movie Database API Documentation!
const movieApiSpec: OpenAPIV3.Document = {
  openapi: '3.0.0',
  info: {
    title: 'CinemaHub API 🎬',
    version: '1.0.0',
    description: 'The ultimate movie database API for film enthusiasts!',
    contact: {
      name: 'CinemaHub Support 🎭',
      email: '[email protected]'
    },
    license: {
      name: 'MIT',
      url: 'https://opensource.org/licenses/MIT'
    }
  },
  servers: [
    {
      url: 'https://api.cinemahub.com/v1',
      description: 'Production server 🚀'
    }
  ],
  paths: {
    '/movies': {
      get: {
        summary: 'Search movies 🔍',
        description: 'Search and filter movies in the database',
        tags: ['Movies'],
        parameters: [
          {
            name: 'query',
            in: 'query',
            description: 'Search query for movie titles',
            schema: { type: 'string' },
            example: 'Avengers'
          },
          {
            name: 'genre',
            in: 'query',
            description: 'Filter by genre 🎭',
            schema: {
              type: 'string',
              enum: ['action', 'comedy', 'drama', 'horror', 'sci-fi', 'romance']
            }
          },
          {
            name: 'year',
            in: 'query',
            description: 'Filter by release year 📅',
            schema: { type: 'integer', minimum: 1900, maximum: 2024 }
          },
          {
            name: 'rating',
            in: 'query',
            description: 'Minimum rating (1-10) ⭐',
            schema: { type: 'number', minimum: 1, maximum: 10 }
          },
          {
            name: 'page',
            in: 'query',
            description: 'Page number for pagination 📄',
            schema: { type: 'integer', minimum: 1, default: 1 }
          },
          {
            name: 'limit',
            in: 'query',
            description: 'Number of items per page',
            schema: { type: 'integer', minimum: 1, maximum: 100, default: 20 }
          }
        ],
        responses: {
          '200': {
            description: 'Movies retrieved successfully 🎉',
            content: {
              'application/json': {
                schema: {
                  type: 'object',
                  properties: {
                    movies: {
                      type: 'array',
                      items: { $ref: '#/components/schemas/Movie' }
                    },
                    pagination: { $ref: '#/components/schemas/Pagination' }
                  }
                }
              }
            }
          },
          '400': {
            description: 'Invalid query parameters',
            content: {
              'application/json': {
                schema: { $ref: '#/components/schemas/Error' }
              }
            }
          }
        }
      },
      post: {
        summary: 'Add a new movie 🎬',
        description: 'Create a new movie entry (Admin only)',
        tags: ['Movies'],
        security: [{ bearerAuth: [] }],
        requestBody: {
          required: true,
          content: {
            'application/json': {
              schema: { $ref: '#/components/schemas/MovieInput' }
            }
          }
        },
        responses: {
          '201': {
            description: 'Movie created successfully 🎊',
            content: {
              'application/json': {
                schema: { $ref: '#/components/schemas/Movie' }
              }
            }
          },
          '400': {
            description: 'Invalid movie data',
            content: {
              'application/json': {
                schema: { $ref: '#/components/schemas/Error' }
              }
            }
          },
          '401': {
            description: 'Unauthorized - Admin access required 🔒'
          }
        }
      }
    },
    '/movies/{id}': {
      get: {
        summary: 'Get movie details 🎬',
        description: 'Retrieve detailed information about a specific movie',
        tags: ['Movies'],
        parameters: [
          {
            name: 'id',
            in: 'path',
            required: true,
            description: 'Movie ID',
            schema: { type: 'string' },
            example: 'movie-123'
          }
        ],
        responses: {
          '200': {
            description: 'Movie details retrieved successfully',
            content: {
              'application/json': {
                schema: { $ref: '#/components/schemas/MovieDetailed' }
              }
            }
          },
          '404': {
            description: 'Movie not found 😞'
          }
        }
      }
    },
    '/movies/{id}/reviews': {
      get: {
        summary: 'Get movie reviews 📝',
        description: 'Retrieve reviews for a specific movie',
        tags: ['Reviews'],
        parameters: [
          {
            name: 'id',
            in: 'path',
            required: true,
            description: 'Movie ID',
            schema: { type: 'string' }
          }
        ],
        responses: {
          '200': {
            description: 'Reviews retrieved successfully',
            content: {
              'application/json': {
                schema: {
                  type: 'array',
                  items: { $ref: '#/components/schemas/Review' }
                }
              }
            }
          }
        }
      },
      post: {
        summary: 'Add a movie review ⭐',
        description: 'Submit a review for a movie',
        tags: ['Reviews'],
        security: [{ bearerAuth: [] }],
        parameters: [
          {
            name: 'id',
            in: 'path',
            required: true,
            description: 'Movie ID',
            schema: { type: 'string' }
          }
        ],
        requestBody: {
          required: true,
          content: {
            'application/json': {
              schema: { $ref: '#/components/schemas/ReviewInput' }
            }
          }
        },
        responses: {
          '201': {
            description: 'Review added successfully 🎉',
            content: {
              'application/json': {
                schema: { $ref: '#/components/schemas/Review' }
              }
            }
          }
        }
      }
    }
  },
  components: {
    schemas: {
      Movie: {
        type: 'object',
        properties: {
          id: { type: 'string', example: 'movie-123' },
          title: { type: 'string', example: 'The Awesome Movie 🎬' },
          description: { 
            type: 'string',
            example: 'An incredible adventure that will blow your mind!'
          },
          genre: { 
            type: 'array',
            items: { type: 'string' },
            example: ['action', 'adventure', 'sci-fi']
          },
          releaseYear: { type: 'integer', example: 2024 },
          rating: { type: 'number', format: 'float', example: 8.5 },
          duration: { type: 'integer', example: 142 },
          director: { type: 'string', example: 'Steven Spielberg 🎭' },
          cast: {
            type: 'array',
            items: { type: 'string' },
            example: ['Actor One 🎭', 'Actor Two 🌟', 'Actor Three ⭐']
          },
          posterUrl: { 
            type: 'string',
            format: 'uri',
            example: 'https://example.com/poster.jpg'
          },
          createdAt: { type: 'string', format: 'date-time' },
          updatedAt: { type: 'string', format: 'date-time' }
        },
        required: ['id', 'title', 'genre', 'releaseYear', 'rating']
      },
      MovieDetailed: {
        allOf: [
          { $ref: '#/components/schemas/Movie' },
          {
            type: 'object',
            properties: {
              reviews: {
                type: 'array',
                items: { $ref: '#/components/schemas/Review' }
              },
              averageRating: { type: 'number', format: 'float' },
              reviewCount: { type: 'integer' }
            }
          }
        ]
      },
      MovieInput: {
        type: 'object',
        properties: {
          title: { type: 'string', minLength: 1 },
          description: { type: 'string' },
          genre: {
            type: 'array',
            items: {
              type: 'string',
              enum: ['action', 'comedy', 'drama', 'horror', 'sci-fi', 'romance']
            }
          },
          releaseYear: { type: 'integer', minimum: 1900, maximum: 2024 },
          duration: { type: 'integer', minimum: 1 },
          director: { type: 'string' },
          cast: {
            type: 'array',
            items: { type: 'string' }
          },
          posterUrl: { type: 'string', format: 'uri' }
        },
        required: ['title', 'genre', 'releaseYear']
      },
      Review: {
        type: 'object',
        properties: {
          id: { type: 'string', example: 'review-456' },
          movieId: { type: 'string', example: 'movie-123' },
          userId: { type: 'string', example: 'user-789' },
          username: { type: 'string', example: 'MovieLover123 🍿' },
          rating: { type: 'integer', minimum: 1, maximum: 10, example: 9 },
          comment: { 
            type: 'string',
            example: 'Absolutely amazing! A masterpiece of cinema 🎬✨'
          },
          createdAt: { type: 'string', format: 'date-time' }
        },
        required: ['id', 'movieId', 'userId', 'rating']
      },
      ReviewInput: {
        type: 'object',
        properties: {
          rating: { type: 'integer', minimum: 1, maximum: 10 },
          comment: { type: 'string', maxLength: 1000 }
        },
        required: ['rating']
      },
      Pagination: {
        type: 'object',
        properties: {
          page: { type: 'integer', example: 1 },
          limit: { type: 'integer', example: 20 },
          total: { type: 'integer', example: 150 },
          pages: { type: 'integer', example: 8 }
        }
      },
      Error: {
        type: 'object',
        properties: {
          code: { type: 'string', example: 'VALIDATION_ERROR' },
          message: { type: 'string', example: 'The provided data is invalid' },
          details: {
            type: 'array',
            items: { type: 'string' },
            example: ['Title is required', 'Genre must be valid']
          }
        }
      }
    },
    securitySchemes: {
      bearerAuth: {
        type: 'http',
        scheme: 'bearer',
        bearerFormat: 'JWT',
        description: 'Enter your JWT token 🔑'
      }
    }
  }
};

// 🎮 Express.js implementation
app.get('/movies', async (req, res) => {
  const { query, genre, year, rating, page = 1, limit = 20 } = req.query;
  
  try {
    const movies = await movieService.searchMovies({
      query: query as string,
      genre: genre as string,
      year: year ? parseInt(year as string) : undefined,
      rating: rating ? parseFloat(rating as string) : undefined,
      page: parseInt(page as string),
      limit: parseInt(limit as string)
    });
    
    res.json({
      movies: movies.data,
      pagination: {
        page: movies.page,
        limit: movies.limit,
        total: movies.total,
        pages: Math.ceil(movies.total / movies.limit)
      }
    });
  } catch (error) {
    res.status(400).json({
      code: 'SEARCH_ERROR',
      message: 'Failed to search movies',
      details: [error.message]
    });
  }
});

🎓 Key Takeaways

You’ve learned so much! Here’s what you can now do:

  • ✅ Create comprehensive API documentation with confidence 💪
  • ✅ Avoid common mistakes that trip up API developers 🛡️
  • ✅ Apply best practices in real projects 🎯
  • ✅ Debug documentation issues like a pro 🐛
  • ✅ Build awesome APIs with TypeScript! 🚀

Remember: Good API documentation is like a friendly guide that helps developers succeed with your API. It’s not just about the code - it’s about creating a great developer experience! 🤝

🤝 Next Steps

Congratulations! 🎉 You’ve mastered API Documentation with Swagger/OpenAPI!

Here’s what to do next:

  1. 💻 Practice documenting your own APIs
  2. 🏗️ Set up automated documentation generation
  3. 📚 Move on to our next tutorial: Authentication & JWT
  4. 🌟 Share your beautiful API docs with the community!

Remember: Every great API starts with great documentation. Keep building, keep documenting, and most importantly, have fun! 🚀

Happy coding! 🎉🚀✨

Previous Tutorial
📘 Validation: Class-Validator and Joi
Next Tutorial
🧪 Testing Node.js Apps: Jest and Supertest

More typescript Tutorials

Part 212

📘 Validation: Class-Validator and Joi

🚀Intermediate • 25 min read
Part 213 - Currently Reading

📘 API Documentation: Swagger/OpenAPI

🚀Intermediate • 25 min read
Part 214

🧪 Testing Node.js Apps: Jest and Supertest

🚀Intermediate • 30 min read
View all 354 typescript tutorials →

Tutorial Info

Series Progress
Part 213 of 354 60%
Category
📘 typescript
Difficulty
🚀Intermediate
Duration
25 min read
Published
June 24, 2025