API Controller

Purpose

Generate a REST controller with full OpenAPI/Swagger documentation including API tags, operation summaries, response schemas, authentication decorators, and auto-translated error responses.

When to Use

• •Creating HTTP endpoints for features
• •Adding new routes to existing controllers
• •Generating Swagger documentation
• •Exposing CRUD operations via REST API

What It Generates

apps/api/src/modules/{feature}/{feature}.controller.ts

Patterns Enforced

OpenAPI Documentation

• •@ApiTags() decorator for grouping endpoints
• •@ApiOperation() with summary and description
• •@ApiResponse() for all possible status codes
• •@ApiBearerAuth() for protected endpoints
• •@ApiProperty() on all DTO fields

HTTP Status Codes

• •200 OK - Successful GET
• •201 Created - Successful POST
• •204 No Content - Successful DELETE
• •400 Bad Request - Validation errors
• •401 Unauthorized - Missing/invalid auth
• •403 Forbidden - Insufficient permissions
• •404 Not Found - Resource not found
• •409 Conflict - Duplicate/resource conflict
• •500 Internal Server Error - Server errors

Consistent Response Format

{
  data?: T;
  error?: {
    code: string;
    message: string;
    locale?: string; // Auto-translated based on Accept-Language
    details?: any;
  };
}

Error Responses with Auto-Translation

All error responses are automatically translated based on the request locale:

// English (default)
{
  "error": {
    "code": "USER_001",
    "message": "User with ID 123 not found",
    "locale": "en"
  }
}

// Spanish (via Accept-Language: es)
{
  "error": {
    "code": "USER_001",
    "message": "Usuario con ID 123 no encontrado",
    "locale": "es"
  }
}

Auto-translation is handled by GlobalExceptionFilter using the error.translated getter.

Usage Example

/skill api-controller --name=Product --operations='create,update,delete,getList,getOne'

Related Files

• •Feature CQRS - Complete CQRS feature with controller
• •API DTO - DTOs for request/response