feat: create doc for email endpoint (#83)

GTBitsOfGood · Mar 30, 2024 · ccb0140 · ccb0140
1 parent b88b740
commit ccb0140
Show file tree

Hide file tree

Showing 3 changed files with 48 additions and 0 deletions.
diff --git a/packages/api-gateway/src/main.ts b/packages/api-gateway/src/main.ts
@@ -18,6 +18,7 @@ async function bootstrap() {
     .setTitle('Juno')
     .setDescription('Juno Public API Docs')
     .setVersion('1.0')
+    .addBearerAuth({ type: 'http', scheme: 'bearer', bearerFormat: 'JWT' })
     .build();
   const document = SwaggerModule.createDocument(app, config);
   SwaggerModule.setup('docs', app, document);

diff --git a/packages/api-gateway/src/models/email.ts b/packages/api-gateway/src/models/email.ts
@@ -6,14 +6,17 @@ import {
 } from 'class-validator';
 import { Type } from 'class-transformer';
 import { EmailProto } from 'juno-proto';
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
 
 export class RegisterEmailModel {
+  @ApiProperty({ type: 'string', format: 'email' })
   @IsNotEmpty()
   @IsEmail()
   email: string;
 }
 
 export class RegisterEmailResponse {
+  @ApiProperty({ type: 'string', format: 'email' })
   email: string;
 
   constructor(email: string) {
@@ -22,41 +25,56 @@ export class RegisterEmailResponse {
 }
 
 class EmailRecipient {
+  @ApiProperty({ type: 'string', format: 'email' })
   @IsNotEmpty()
   @IsEmail()
   email: string;
+
+  @ApiPropertyOptional({ type: 'string', example: 'John Doe' })
   name?: string | undefined;
 }
 
 class EmailSender {
+  @ApiProperty({ type: 'string', format: 'email' })
   @IsNotEmpty()
   @IsEmail()
   email: string;
+
+  @ApiPropertyOptional({ type: 'string', example: 'John Doe' })
   name?: string | undefined;
 }
 
 class EmailContent {
+  @ApiProperty({ type: 'string', example: 'text/html' })
   @IsNotEmpty()
   type: string;
+
+  @ApiProperty({ type: 'string', example: 'Email content' })
   @IsNotEmpty()
   value: string;
 }
 
 export class SendEmailModel {
+  @ApiProperty({ type: [EmailRecipient] })
   @ArrayNotEmpty()
   @ValidateNested({ each: true })
   @Type(() => EmailRecipient)
   recipients: EmailRecipient[];
+
+  @ApiProperty({ type: EmailSender })
   @ValidateNested({ each: true })
   @Type(() => EmailSender)
   sender: EmailSender | undefined;
+
+  @ApiProperty({ type: [EmailContent] })
   @ArrayNotEmpty()
   @ValidateNested({ each: true })
   @Type(() => EmailContent)
   content: EmailContent[];
 }
 
 export class SendEmailResponse {
+  @ApiProperty({ type: 'boolean' })
   success: boolean;
 
   constructor(res: EmailProto.SendEmailResponse) {

diff --git a/packages/api-gateway/src/modules/email/email.controller.ts b/packages/api-gateway/src/modules/email/email.controller.ts
@@ -19,8 +19,19 @@ import { EmailProto } from 'juno-proto';
 import { plainToInstance } from 'class-transformer';
 import { validateOrReject } from 'class-validator';
 
+import {
+  ApiBearerAuth,
+  ApiUnauthorizedResponse,
+  ApiBadRequestResponse,
+  ApiTags,
+  ApiCreatedResponse,
+  ApiOperation,
+} from '@nestjs/swagger';
+
 const { EMAIL_SERVICE_NAME } = EmailProto;
 
+@ApiBearerAuth()
+@ApiTags('email')
 @Controller('email')
 export class EmailController implements OnModuleInit {
   private emailService: EmailProto.EmailServiceClient;
@@ -34,11 +45,29 @@ export class EmailController implements OnModuleInit {
       );
   }
 
+  @ApiOperation({
+    description: 'This endpoint registers a user',
+  })
+  @ApiCreatedResponse({
+    description: 'Email registered successfully',
+    type: RegisterEmailResponse,
+  })
+  @ApiUnauthorizedResponse({ description: 'Unauthorized' })
+  @ApiBadRequestResponse({ description: 'Bad Request' })
   @Post('register')
   async registerSenderAddress(@Body('') params: RegisterEmailModel) {
     return new RegisterEmailResponse(params.email);
   }
 
+  @ApiOperation({
+    description: 'This endpoint sends an email',
+  })
+  @ApiCreatedResponse({
+    description: 'Email sent successfully',
+    type: SendEmailResponse,
+  })
+  @ApiUnauthorizedResponse({ description: 'Unauthorized' })
+  @ApiBadRequestResponse({ description: 'Bad Request' })
   @Post('/send')
   async sendEmail(@Body() req: SendEmailModel): Promise<SendEmailResponse> {
     if (!req) {