[Server]: Comprehensive API Documentation with Swagger/OpenAPI

[NightClover-code]

Description:

Currently, only the authentication routes (/auth/register and /auth/login) are well documented with Swagger decorators.

We need to extend this documentation to all API endpoints for a better developer experience.

Current example of well-documented endpoint:

export class LoginDto {
  @ApiProperty({
    example: '[email protected]',
  })
  @IsEmail()
  email!: string;

  @ApiProperty({
    example: 'password123',
    minLength: 5,
    maxLength: 20,
  })
  @IsString()
  password!: string;
}

Tasks

1. Add Swagger documentation for Products endpoints:

• GET /products - List products with pagination
• GET /products/topRated - Get top rated products
• GET /products/:id - Get single product
• POST /products - Create product (admin)
• PUT /products/:id - Update product (admin)
• DELETE /products/:id - Delete product (admin)
• PUT /products/:id/review - Create product review

2. Add Swagger documentation for Orders endpoints:

• POST /orders - Create order
• GET /orders - Get all orders (admin)
• GET /orders/myorders - Get user orders
• GET /orders/:id - Get order by ID
• PUT /orders/:id/pay - Update order to paid
• PUT /orders/:id/deliver - Update order to delivered

3. Add Swagger documentation for Cart endpoints:

• POST /cart - Add to cart
• POST /cart/shipping - Save shipping address
• POST /cart/payment - Save payment method

4. Add Swagger documentation for Users endpoints:

• GET /users - Get all users (admin)
• DELETE /users/:id - Delete user (admin)
• GET /users/:id - Get user by ID (admin)
• PUT /users/:id - Update user (admin)

5. Add Swagger documentation for Upload endpoint:

• POST /upload - Upload image

For each endpoint, include:

• Route description
• Request parameters
• Request body schema (when applicable)
• Response schema
• Possible error responses
• Authentication requirements
• Example requests and responses

Example Implentation:

@ApiTags('products')
@Controller('products')
export class ProductsController {
  @ApiOperation({ summary: 'Get all products' })
  @ApiQuery({ name: 'keyword', required: false, description: 'Search keyword' })
  @ApiQuery({ name: 'pageId', required: false, description: 'Page number' })
  @ApiResponse({ 
    status: 200, 
    description: 'Returns paginated products',
    type: PaginatedProductsResponse 
  })
  @ApiResponse({ status: 404, description: 'No products found' })
  @Get()
  getProducts(
    @Query('keyword') keyword: string,
    @Query('pageId') pageId: string,
  ) {
    return this.productsService.findMany(keyword, pageId);
  }
}