Menu
Swagger/OpenAPI setup and documentation patterns for SE104_VLEAGUE
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Complete guide for the SE104_VLEAGUE React frontend — pages, services, components, auth flow, i18n, and patterns
Complete guide for testing patterns, test structure, CI pipeline, and development workflow for SE104_VLEAGUE
Complete guide for the SE104_VLEAGUE NestJS backend — modules, endpoints, Prisma schema, guards, interceptors, and patterns
JWT auth, OAuth, OTP verification, session management, RBAC for SE104_VLEAGUE
All business rules, state machines, scoring, regulations, and domain constraints for SE104_VLEAGUE
Prisma schema, migrations, seeding, and database operations for SE104_VLEAGUE
| name | API Documentation |
| description | Swagger/OpenAPI setup and documentation patterns for SE104_VLEAGUE |
Swagger UI available at /api/docs (set up in main.ts).
const config = new DocumentBuilder()
.setTitle('VLeague API')
.setDescription('V-League Football Management System API')
.setVersion('1.0')
.addBearerAuth(
{
type: 'http',
scheme: 'bearer',
bearerFormat: 'JWT',
name: 'JWT',
description: 'Enter JWT access token',
in: 'header',
},
'access-token',
)
.addTag('Authentication', 'User authentication endpoints')
.addTag('Teams', 'Team management endpoints')
.addTag('Players', 'Player management endpoints')
.addTag('Matches', 'Match scheduling and management')
.addTag('Scheduling', 'Schedule generation and publishing')
.addTag('Seasons', 'Season management')
.addTag('Stadiums', 'Stadium management')
.addTag('Roster', 'Team roster management')
.addTag('Regulations', 'Season regulations')
.addTag('Standings', 'League standings & statistics')
.addTag('Users', 'User management (ADMIN)')
.addTag('Upload', 'File upload')
.addTag('Search', 'Global search')
.addTag('Health', 'Health check')
.build();
const document = SwaggerModule.createDocument(app, config);
SwaggerModule.setup('docs', app, document);
@ApiTags('Teams')
@Controller('teams')
export class TeamsController {
@Get()
@ApiOperation({ summary: 'List all teams' })
@ApiResponse({ status: 200, description: 'Teams retrieved successfully' })
@Public()
findAll(@Query() query: PaginationQueryDto) {}
@Post()
@ApiOperation({ summary: 'Create a team' })
@ApiResponse({ status: 201, description: 'Team created' })
@ApiResponse({ status: 409, description: 'Team name already exists' })
@ApiBearerAuth()
@Roles(UserRole.ADMIN)
create(@Body() dto: CreateTeamDto) {}
}
export class CreateTeamDto {
@ApiProperty({ description: 'Team name', example: 'Hoàng Anh Gia Lai' })
@IsString()
@IsNotEmpty()
name: string;
@ApiPropertyOptional({ description: 'Short name', example: 'HAGL' })
@IsOptional()
@IsString()
shortName?: string;
@ApiPropertyOptional({ description: 'City', example: 'Pleiku' })
@IsOptional()
@IsString()
city?: string;
@ApiPropertyOptional({ enum: TeamStatus, default: TeamStatus.ACTIVE })
@IsOptional()
@IsEnum(TeamStatus)
status?: TeamStatus;
}
All API errors follow this schema:
{
"statusCode": 400,
"code": "VALIDATION_ERROR",
"message": "Validation failed",
"details": ["field must be a string"],
"requestId": "uuid",
"timestamp": "2026-01-01T00:00:00.000Z"
}
| Decorator | Purpose |
|---|---|
@ApiTags('Tag') | Group endpoints by tag |
@ApiOperation({ summary }) | Endpoint description |
@ApiResponse({ status, description }) | Response documentation |
@ApiBearerAuth() | Mark as JWT-protected |
@ApiProperty({ description, example }) | Required field |
@ApiPropertyOptional({...}) | Optional field |
@ApiQuery({ name, required, enum }) | Query parameter |
@ApiParam({ name, description }) | Path parameter |
@ApiConsumes('multipart/form-data') | File upload endpoint |