Add swagger documentation

nest-cli.json

@@ -3,6 +3,7 @@
   "collection": "@nestjs/schematics",
   "sourceRoot": "src",
   "compilerOptions": {
-    "deleteOutDir": true
+    "deleteOutDir": true,
+    "plugins": ["@nestjs/swagger"]
   }
 }

package.json

@@ -51,6 +51,7 @@
     "@nestjs/jwt": "^11.0.2",
     "@nestjs/mapped-types": "*",
     "@nestjs/platform-express": "^11.0.1",
+    "@nestjs/swagger": "^11.2.6",
     "@nestjs/throttler": "^6.5.0",
     "@prisma/adapter-pg": "^7.4.0",
     "@prisma/client": "^7.4.2",

src/app.controller.ts

@@ -1,7 +1,9 @@
 import { Controller, Get } from '@nestjs/common'
+import { ApiTags } from '@nestjs/swagger'
 import { AppService } from './app.service'
 import { Public } from './auth/decorator'
 
+@ApiTags('App')
 @Controller()
 export class AppController {
   constructor(private readonly appService: AppService) {}

src/auth/auth.controller.ts

@@ -7,6 +7,7 @@ import {
   Post,
   UseGuards,
 } from '@nestjs/common'
+import { ApiBearerAuth, ApiTags } from '@nestjs/swagger'
 import { OtpService } from 'src/otp/otp.service'
 import { TokenService } from 'src/token/token.service'
 import { CreateUserDto } from 'src/user/dto'
@@ -22,6 +23,7 @@ import {
 } from './dto'
 import { RefreshTokenGuard } from './guard'
 
+@ApiTags('Auth')
 @Controller('auth')
 export class AuthController {
   constructor(
@@ -43,13 +45,15 @@ export class AuthController {
     return this.authService.login(loginDto)
   }
 
+  @ApiBearerAuth()
   @HttpCode(HttpStatus.OK)
   @Post('logout-all')
   logoutAll(@User('sub') userId: number) {
     return this.authService.logoutFromAllDevices(userId)
   }
 
   @Public()
+  @ApiBearerAuth()
   @UseGuards(RefreshTokenGuard)
   @HttpCode(HttpStatus.OK)
   @Post('refresh-token')
@@ -61,13 +65,15 @@ export class AuthController {
   }
 
   @Public()
+  @ApiBearerAuth()
   @UseGuards(RefreshTokenGuard)
   @HttpCode(HttpStatus.OK)
   @Post('revoke-refresh-token')
   revokeRefreshToken(@User('rtid') refreshTokenId: string) {
     return this.tokenService.revokeRefreshToken(refreshTokenId)
   }
 
+  @ApiBearerAuth()
   @Patch('change-email')
   changeEmail(
     @User('email') oldEmail: string,
@@ -76,6 +82,7 @@ export class AuthController {
     return this.authService.changeEmail(oldEmail, changeEmailDto)
   }
 
+  @ApiBearerAuth()
   @Patch('change-password')
   changePassword(
     @User('email') email: string,
@@ -97,6 +104,7 @@ export class AuthController {
     return this.otpService.emailOtp(emailOtpDto.email)
   }
 
+  @ApiBearerAuth()
   @HttpCode(HttpStatus.OK)
   @Post('guarded-email-otp')
   guardedEmailOtp(@User('email') email: string) {

src/auth/auth.service.ts

@@ -5,6 +5,7 @@ import {
   NotFoundException,
 } from '@nestjs/common'
 import * as argon from 'argon2'
+import { UserAlreadyExistsException } from 'src/custom-exceptions'
 import { PrismaService } from 'src/infra/prisma/prisma.service'
 import { OtpService } from 'src/otp/otp.service'
 import { TokenService } from 'src/token/token.service'
@@ -27,6 +28,13 @@ export class AuthService {
   ) {}
 
   public async signup(createUserDto: CreateUserDto) {
+    // validate if a user exists with the same email
+    const existingUser = await this.prisma.user.findUnique({
+      where: { email: createUserDto.email },
+      select: { email: true },
+    })
+    if (existingUser)
+      throw new UserAlreadyExistsException('email', existingUser.email)
     const { emailVerifiedCode, ...dto } = createUserDto
     await this.otpService.verifyCode(dto.email, emailVerifiedCode)
     const user = await this.usersService.createUser(dto)
@@ -44,7 +52,7 @@ export class AuthService {
     // if user does not exist, throw exception
     if (!user) throw new NotFoundException('User not found')
     // check user is not active (deleted)
-    if (user.deleted) throw new ForbiddenException('User inactive')
+    if (user.deleted) throw new ForbiddenException('User account inactive')
     // compare password
     const pwMatches = await argon.verify(user.password, loginDto.password)
     // if the password incorrect, throw exception

src/auth/dto/change-email.dto.ts

@@ -1,14 +1,19 @@
+import { ApiProperty, ApiSchema } from '@nestjs/swagger'
 import { IsEmail, IsNotEmpty, IsString } from 'class-validator'
 
+@ApiSchema({ name: 'ChangeEmailRequest' })
 export class ChangeEmailDto {
+  @ApiProperty({ example: 'new_email@example.com' })
   @IsEmail()
   @IsNotEmpty()
   newEmail: string
 
+  @ApiProperty({ example: '019cdba1-96a7-7471-be71-42636407ce41' })
   @IsString()
   @IsNotEmpty()
   oldEmailVerifiedCode: string
 
+  @ApiProperty({ example: '019cdba1-96a7-7471-be71-42636407ce41' })
   @IsString()
   @IsNotEmpty()
   newEmailVerifiedCode: string

src/auth/dto/change-password.dto.ts

@@ -1,14 +1,19 @@
+import { ApiProperty, ApiSchema } from '@nestjs/swagger'
 import { IsNotEmpty, IsString } from 'class-validator'
 
+@ApiSchema({ name: 'ChangePasswordRequest' })
 export class ChangePasswordDto {
+  @ApiProperty({ example: 'oldPassword123' })
   @IsString()
   @IsNotEmpty()
   oldPassword: string
 
+  @ApiProperty({ example: 'newPassword123' })
   @IsString()
   @IsNotEmpty()
   newPassword: string
 
+  @ApiProperty({ example: '019cdba1-96a7-7471-be71-42636407ce41' })
   @IsString()
   @IsNotEmpty()
   emailVerifiedCode: string

src/auth/dto/forgot-password.dto.ts

@@ -1,14 +1,19 @@
+import { ApiProperty, ApiSchema } from '@nestjs/swagger'
 import { IsNotEmpty, IsString } from 'class-validator'
 
+@ApiSchema({ name: 'ForgotPasswordRequest' })
 export class ForgotPasswordDto {
+  @ApiProperty({ example: 'user@example.com' })
   @IsString()
   @IsNotEmpty()
   email: string
 
+  @ApiProperty({ example: 'newPassword123' })
   @IsString()
   @IsNotEmpty()
   newPassword: string
 
+  @ApiProperty({ example: '019cdba1-96a7-7471-be71-42636407ce41' })
   @IsString()
   @IsNotEmpty()
   emailVerifiedCode: string

src/auth/dto/login.dto.ts

@@ -1,10 +1,20 @@
+import { ApiProperty, ApiSchema } from '@nestjs/swagger'
 import { IsEmail, IsNotEmpty, IsString } from 'class-validator'
 
+@ApiSchema({ name: 'LoginRequest' })
 export class LoginDto {
+  @ApiProperty({
+    example: 'user@example.com',
+    description: 'The email address of the user',
+  })
   @IsEmail()
   @IsNotEmpty()
   email: string
 
+  @ApiProperty({
+    example: 'password123',
+    description: 'The password of the user',
+  })
   @IsString()
   @IsNotEmpty()
   password: string

src/auth/dto/otp.dto.ts

@@ -1,16 +1,22 @@
+import { ApiProperty, ApiSchema } from '@nestjs/swagger'
 import { IsEmail, IsNotEmpty, IsString } from 'class-validator'
 
+@ApiSchema({ name: 'EmailOtpRequest' })
 export class EmailOtpDto {
+  @ApiProperty({ example: 'user@example.com' })
   @IsEmail()
   @IsNotEmpty()
   email: string
 }
 
+@ApiSchema({ name: 'VerifyOtpRequest' })
 export class VerifyOtpDto {
+  @ApiProperty({ example: 'user@example.com' })
   @IsEmail()
   @IsNotEmpty()
   email: string
 
+  @ApiProperty({ example: '123456' })
   @IsString()
   @IsNotEmpty()
   otp: string

src/auth/guard/auth.guard.spec.ts

@@ -104,7 +104,7 @@ describe('AuthGuard', () => {
     mockPrisma.user.findUnique.mockResolvedValue(null)
 
     await expect(guard.canActivate(context)).rejects.toThrow(
-      new NotFoundException('User not exists'),
+      new NotFoundException('Your account not exists'),
     )
   })
 
@@ -115,7 +115,7 @@ describe('AuthGuard', () => {
     mockPrisma.user.findUnique.mockResolvedValue({ deleted: true })
 
     await expect(guard.canActivate(context)).rejects.toThrow(
-      new ForbiddenException('User inactive'),
+      new ForbiddenException('Your account is inactive'),
     )
   })
 
@@ -129,7 +129,7 @@ describe('AuthGuard', () => {
     }) // user version 2
 
     await expect(guard.canActivate(context)).rejects.toThrow(
-      new UnauthorizedException('Token revoked'),
+      new UnauthorizedException('Access token revoked'),
     )
   })
 

src/auth/guard/auth.guard.ts

@@ -51,12 +51,12 @@ export class AuthGuard implements CanActivate {
         where: { id: payload.sub },
         select: { email: true, role: true, tokenVersion: true, deleted: true },
       })
-      if (!user) throw new NotFoundException('User not exists')
+      if (!user) throw new NotFoundException('Your account not exists')
       // check user is not active (deleted)
-      if (user.deleted) throw new ForbiddenException('User inactive')
+      if (user.deleted) throw new ForbiddenException('Your account is inactive')
 
       if (user.tokenVersion !== payload.version) {
-        throw new UnauthorizedException('Token revoked')
+        throw new UnauthorizedException('Access token revoked')
       }
 
       request[REQUEST_USER_KEY] = {

src/custom-exceptions/index.ts

@@ -0,0 +1 @@
+export * from './user-already-exists.exception'

src/custom-exceptions/user-already-exists.exception.ts

@@ -0,0 +1,10 @@
+import { HttpException, HttpStatus } from '@nestjs/common'
+
+export class UserAlreadyExistsException extends HttpException {
+  constructor(fieldName: string, fieldValue: string) {
+    super(
+      `User with ${fieldName} '${fieldValue}' already exists`,
+      HttpStatus.CONFLICT,
+    )
+  }
+}