From 2a339b211c7c5322a1633f6e5b9219db9bc2d2b7 Mon Sep 17 00:00:00 2001 From: aniebietafia Date: Sun, 3 Nov 2024 19:54:22 +0100 Subject: [PATCH] doc: User management endpoints documention. --- .../users/swagger_docs/common-reponses.doc.ts | 45 +++++++++++++ .../users/swagger_docs/verify-email.doc.ts | 63 +++++++++++++++++++ .../swagger_docs/verify-phone-response.doc.ts | 19 ++++++ .../src/users/users.controller.ts | 47 +++++++------- 4 files changed, 152 insertions(+), 22 deletions(-) create mode 100644 brints-estate-api/src/users/swagger_docs/common-reponses.doc.ts create mode 100644 brints-estate-api/src/users/swagger_docs/verify-email.doc.ts create mode 100644 brints-estate-api/src/users/swagger_docs/verify-phone-response.doc.ts 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 new file mode 100644 index 0000000..b9da72b --- /dev/null +++ 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 new file mode 100644 index 0000000..b49e289 --- /dev/null +++ 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 new file mode 100644 index 0000000..ae34479 --- /dev/null +++ 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 index 5d10df9..5d452c4 100644 --- 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)