doc: User management endpoints documention.

Brints · Nov 3, 2024 · 2a339b2 · 2a339b2
1 parent 86e0093
commit 2a339b2
Show file tree

Hide file tree

Showing 4 changed files with 152 additions and 22 deletions.
diff --git a/brints-estate-api/src/users/swagger_docs/common-reponses.doc.ts b/brints-estate-api/src/users/swagger_docs/common-reponses.doc.ts
@@ -0,0 +1,45 @@
+import { HttpStatus } from '@nestjs/common';
+
+export const UnauthorizedUserVerifiedResponse = {
+  description: 'Unauthorized',
+  status: HttpStatus.UNAUTHORIZED,
+  schema: {
+    type: 'object',
+    properties: {
+      success: {
+        type: 'boolean',
+        example: false,
+      },
+      status_code: {
+        type: 'number',
+        example: HttpStatus.UNAUTHORIZED,
+      },
+      message: {
+        type: 'string',
+        example: 'User already verified',
+      },
+    },
+  },
+};
+
+export const InternalServerErrorResponse = {
+  description: 'Internal server error',
+  status: HttpStatus.INTERNAL_SERVER_ERROR,
+  schema: {
+    type: 'object',
+    properties: {
+      success: {
+        type: 'boolean',
+        example: false,
+      },
+      status_code: {
+        type: 'number',
+        example: HttpStatus.INTERNAL_SERVER_ERROR,
+      },
+      message: {
+        type: 'string',
+        example: 'Internal server error. Please try again later',
+      },
+    },
+  },
+};
diff --git a/brints-estate-api/src/users/swagger_docs/verify-email.doc.ts b/brints-estate-api/src/users/swagger_docs/verify-email.doc.ts
@@ -0,0 +1,63 @@
+import { HttpStatus } from '@nestjs/common';
+
+export const BadRequestInvalidTokenResponse = {
+  description: 'Bad request',
+  status: HttpStatus.BAD_REQUEST,
+  schema: {
+    type: 'object',
+    properties: {
+      success: {
+        type: 'boolean',
+        example: false,
+      },
+      status_code: {
+        type: 'number',
+        example: HttpStatus.BAD_REQUEST,
+      },
+      message: {
+        type: 'string',
+        example: 'Invalid token',
+      },
+    },
+  },
+};
+
+export const ForbiddenTokenExpiredResponse = {
+  description: 'Forbidden',
+  status: HttpStatus.FORBIDDEN,
+  schema: {
+    type: 'object',
+    properties: {
+      success: {
+        type: 'boolean',
+        example: false,
+      },
+      status_code: {
+        type: 'number',
+        example: HttpStatus.FORBIDDEN,
+      },
+      message: {
+        type: 'string',
+        example: 'Token expired',
+      },
+    },
+  },
+};
+
+export const VerifyEmailResponse = {
+  description: 'User email verified successfully',
+  status: HttpStatus.OK,
+  schema: {
+    type: 'object',
+    properties: {
+      status_code: {
+        type: 'number',
+        example: HttpStatus.OK,
+      },
+      message: {
+        type: 'string',
+        example: 'Your email has been verified successfully.',
+      },
+    },
+  },
+};
diff --git a/brints-estate-api/src/users/swagger_docs/verify-phone-response.doc.ts b/brints-estate-api/src/users/swagger_docs/verify-phone-response.doc.ts
@@ -0,0 +1,19 @@
+import { HttpStatus } from '@nestjs/common';
+
+export const VerifyPhoneResponse = {
+  description: 'User phone number verified successfully',
+  status: HttpStatus.OK,
+  schema: {
+    type: 'object',
+    properties: {
+      status_code: {
+        type: 'number',
+        example: HttpStatus.OK,
+      },
+      message: {
+        type: 'string',
+        example: 'Your phone number has been verified successfully.',
+      },
+    },
+  },
+};
diff --git a/brints-estate-api/src/users/users.controller.ts b/brints-estate-api/src/users/users.controller.ts
@@ -14,6 +14,8 @@ import {
 } from '@nestjs/common';
 import {
   ApiBearerAuth,
+  ApiInternalServerErrorResponse,
+  ApiOkResponse,
   ApiOperation,
   ApiResponse,
   ApiTags,
@@ -34,34 +36,30 @@ import { ForgotPasswordDto } from './dto/forgot-password.dto';
 import { IResetPassword } from './interface/reset-password.interface';
 import { UpdateUserDto } from './dto/update-user.dto';
 
+import {
+  BadRequestInvalidTokenResponse,
+  ForbiddenTokenExpiredResponse,
+  VerifyEmailResponse,
+} from './swagger_docs/verify-email.doc';
+import {
+  InternalServerErrorResponse,
+  UnauthorizedUserVerifiedResponse,
+} from './swagger_docs/common-reponses.doc';
+import { VerifyPhoneResponse } from './swagger_docs/verify-phone-response.doc';
+
 @Controller('user')
-@ApiTags('Users')
+@ApiTags('User Management')
 export class UsersController {
   constructor(private readonly usersService: UsersService) {}
 
   @ApiOperation({
-    summary: 'Verifies user email address.',
-  })
-  @ApiResponse({
-    status: HttpStatus.OK,
-    description: 'User email verified successfully',
-  })
-  @ApiResponse({
-    status: HttpStatus.BAD_REQUEST,
-    description: 'Invalid token',
-  })
-  @ApiResponse({
-    status: HttpStatus.FORBIDDEN,
-    description: 'Token expired',
-  })
-  @ApiResponse({
-    status: HttpStatus.UNAUTHORIZED,
-    description: 'User already verified',
-  })
-  @ApiResponse({
-    status: HttpStatus.INTERNAL_SERVER_ERROR,
-    description: 'Internal server error. Please try again later',
+    summary: 'Verify registered user email address.',
   })
+  @ApiResponse(VerifyEmailResponse)
+  @ApiResponse(BadRequestInvalidTokenResponse)
+  @ApiResponse(ForbiddenTokenExpiredResponse)
+  @ApiResponse(UnauthorizedUserVerifiedResponse)
+  @ApiResponse(InternalServerErrorResponse)
   @Get('verify-email')
   @Auth(AuthType.None)
   @UseInterceptors(ClassSerializerInterceptor)
@@ -76,6 +74,11 @@ export class UsersController {
     };
   }
 
+  @ApiOperation({
+    summary: 'Verify registered user phone number.',
+  })
+  @ApiOkResponse(VerifyPhoneResponse)
+  @ApiInternalServerErrorResponse(InternalServerErrorResponse)
   @Post('verify-phone')
   @Auth(AuthType.None)
   @HttpCode(HttpStatus.OK)