admin/goodgo-platform
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(api): add OpenAPI/Swagger documentation for all API endpoints

Browse Source 
Install @nestjs/swagger, configure Swagger UI at /api/docs with JWT bearer
auth, and add ApiTags/ApiOperation/ApiResponse/ApiProperty decorators to
all 8 controllers (50+ endpoints) and 31 DTOs across auth, listings,
search, payments, subscriptions, admin, notifications, and analytics modules.

Co-Authored-By: Paperclip <noreply@paperclip.ing>
This commit is contained in:
Ho Ngoc Hai
2026-04-08 04:08:11 +07:00
parent 325cd4c421
commit 8e7672694b
42 changed files with 531 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

27
apps/api/src/modules/auth/presentation/controllers/auth.controller.ts
View File

@@ -6,6 +6,7 @@ import {
Post,
UseGuards,
} from '@nestjs/common';
import { ApiTags, ApiOperation, ApiResponse, ApiBearerAuth, ApiBody } from '@nestjs/swagger';
import { CommandBus, QueryBus } from '@nestjs/cqrs';
import { RegisterUserCommand } from '../../application/commands/register-user/register-user.command';
import { LoginUserCommand } from '../../application/commands/login-user/login-user.command';
@@ -14,6 +15,7 @@ import { VerifyKycCommand } from '../../application/commands/verify-kyc/verify-k
import { GetProfileQuery } from '../../application/queries/get-profile/get-profile.query';
import { GetAgentByUserIdQuery } from '../../application/queries/get-agent-by-user-id/get-agent-by-user-id.query';
import { RegisterDto } from '../dto/register.dto';
import { LoginDto } from '../dto/login.dto';
import { RefreshTokenDto } from '../dto/refresh-token.dto';
import { VerifyKycDto } from '../dto/verify-kyc.dto';
import { JwtAuthGuard } from '../guards/jwt-auth.guard';
@@ -25,6 +27,7 @@ import { type JwtPayload, type TokenPair } from '../../infrastructure/services/t
import { type UserProfileDto } from '../../application/queries/get-profile/get-profile.handler';
import { type AgentDto } from '../../application/queries/get-agent-by-user-id/get-agent-by-user-id.handler';
@ApiTags('auth')
@Controller('auth')
export class AuthController {
constructor(
@@ -33,6 +36,10 @@ export class AuthController {
) {}
@Post('register')
@ApiOperation({ summary: 'Register a new user' })
@ApiResponse({ status: 201, description: 'User registered, tokens returned' })
@ApiResponse({ status: 400, description: 'Validation error' })
@ApiResponse({ status: 409, description: 'Phone already registered' })
async register(@Body() dto: RegisterDto): Promise<TokenPair> {
return this.commandBus.execute(
new RegisterUserCommand(dto.phone, dto.password, dto.fullName, dto.email),
@@ -41,6 +48,10 @@ export class AuthController {
@UseGuards(LocalAuthGuard)
@Post('login')
@ApiOperation({ summary: 'Login with phone and password' })
@ApiBody({ type: LoginDto })
@ApiResponse({ status: 201, description: 'Login successful, tokens returned' })
@ApiResponse({ status: 401, description: 'Invalid credentials' })
async login(@CurrentUser() user: { id: string; phone: string; role: string }): Promise<TokenPair> {
return this.commandBus.execute(
new LoginUserCommand(user.id, user.phone, user.role),
@@ -48,18 +59,29 @@ export class AuthController {
}
@Post('refresh')
@ApiOperation({ summary: 'Refresh access token' })
@ApiResponse({ status: 201, description: 'New token pair returned' })
@ApiResponse({ status: 401, description: 'Invalid or expired refresh token' })
async refresh(@Body() dto: RefreshTokenDto): Promise<TokenPair> {
return this.commandBus.execute(new RefreshTokenCommand(dto.refreshToken));
}
@UseGuards(JwtAuthGuard)
@Get('profile')
@ApiBearerAuth('JWT')
@ApiOperation({ summary: 'Get current user profile' })
@ApiResponse({ status: 200, description: 'User profile returned' })
@ApiResponse({ status: 401, description: 'Unauthorized' })
async getProfile(@CurrentUser() user: JwtPayload): Promise<UserProfileDto> {
return this.queryBus.execute(new GetProfileQuery(user.sub));
}
@UseGuards(JwtAuthGuard)
@Get('profile/agent')
@ApiBearerAuth('JWT')
@ApiOperation({ summary: 'Get agent profile for current user' })
@ApiResponse({ status: 200, description: 'Agent profile returned (null if not an agent)' })
@ApiResponse({ status: 401, description: 'Unauthorized' })
async getAgentProfile(@CurrentUser() user: JwtPayload): Promise<AgentDto | null> {
return this.queryBus.execute(new GetAgentByUserIdQuery(user.sub));
}
@@ -67,6 +89,11 @@ export class AuthController {
@UseGuards(JwtAuthGuard, RolesGuard)
@Roles('ADMIN')
@Patch('kyc')
@ApiBearerAuth('JWT')
@ApiOperation({ summary: 'Verify user KYC (admin only)' })
@ApiResponse({ status: 200, description: 'KYC status updated' })
@ApiResponse({ status: 401, description: 'Unauthorized' })
@ApiResponse({ status: 403, description: 'Forbidden — admin only' })
async verifyKyc(
@Body() dto: VerifyKycDto & { userId: string },
): Promise<{ message: string }> {