Merge pull request #146 from gsainfoteam/145-kdh

docs: add http respones in swagger

Author: dohyun06

src/auth/auth.controller.ts

@@ -15,13 +15,14 @@ import {
 import {
   ApiCreatedResponse,
   ApiInternalServerErrorResponse,
+  ApiNotFoundResponse,
   ApiOkResponse,
   ApiOperation,
   ApiTags,
   ApiUnauthorizedResponse,
 } from '@nestjs/swagger';
-import { PublicKeyCredentialRequestOptionsJSON } from '@simplewebauthn/types';
 import { FastifyReply, FastifyRequest } from 'fastify';
+import { PasskeyOptionResDto } from 'src/user/dto/res.dto';
 
 import { AuthService } from './auth.service';
 import {
@@ -142,17 +143,27 @@ export class AuthController {
     summary: 'get the passkey options',
     description: '패스키 로그인을 위한 정보를 불러옵니다.',
   })
+  @ApiOkResponse({
+    description: 'success',
+    type: PasskeyOptionResDto,
+  })
+  @ApiNotFoundResponse({ description: 'Email is not found' })
+  @ApiInternalServerErrorResponse({ description: 'server error' })
   @Post('passkey')
   async authenticateOptions(
     @Body() { email }: PasskeyDto,
-  ): Promise<PublicKeyCredentialRequestOptionsJSON> {
+  ): Promise<PasskeyOptionResDto> {
     return this.authService.authenticateOptions(email);
   }
 
   @ApiOperation({
     summary: 'verify the passkey options',
     description: '패스키를 인증합니다.',
   })
+  @ApiCreatedResponse({ description: 'success', type: LoginResDto })
+  @ApiUnauthorizedResponse({ description: 'Response is invalid' })
+  @ApiNotFoundResponse({ description: 'Email is not found' })
+  @ApiInternalServerErrorResponse({ description: 'server error' })
   @Post('passkey/verify')
   async verifyAuthentication(
     @Body() { email, authenticationResponse }: VerifyPasskeyAuthenticationDto,

src/user/dto/res.dto.ts

@@ -1,5 +1,6 @@
 import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
 import { User } from '@prisma/client';
+import { AuthenticatorTransportFuture } from '@simplewebauthn/types';
 import { Exclude } from 'class-transformer';
 
 import { UserConsentType } from '../types/userConsent.type';
@@ -154,3 +155,72 @@ export class UserConsentListResDto {
   })
   list: UserConsentResDto[];
 }
+
+class AllowCredentialDto {
+  @ApiProperty({
+    description: 'CredentialID of passkey (Base64URL)',
+    example: 'aUF_gprsh...',
+  })
+  id: string;
+
+  @ApiProperty({ description: 'Credential type', example: 'public-key' })
+  type: 'public-key';
+
+  @ApiPropertyOptional({
+    description: 'List of communication method',
+    example: ['internal'],
+  })
+  transports?: AuthenticatorTransportFuture[];
+}
+
+class AuthenticationExtensionsDto {
+  @ApiPropertyOptional({ description: 'appid extension' })
+  appid?: string;
+
+  @ApiPropertyOptional({ description: 'credProps extension' })
+  credProps?: boolean;
+
+  @ApiPropertyOptional({ description: 'hmacCreateSecret extension' })
+  hmacCreateSecret?: boolean;
+
+  @ApiPropertyOptional({ description: 'minPinLength extension' })
+  minPinLength?: boolean;
+}
+
+export class PasskeyOptionResDto {
+  @ApiProperty({
+    description: 'challenge (Base64URL)',
+    example: 'HPv7vydo...',
+  })
+  challenge: string;
+
+  @ApiPropertyOptional({ description: 'request timeout(ms)', example: 60000 })
+  timeout?: number;
+
+  @ApiPropertyOptional({
+    description: 'Relying Party ID',
+    example: 'idp.gistory.me',
+  })
+  rpId?: string;
+
+  @ApiPropertyOptional({
+    example: [AllowCredentialDto],
+    description: 'Passkey list',
+    type: [AllowCredentialDto],
+  })
+  allowCredentials?: AllowCredentialDto[];
+
+  @ApiPropertyOptional({
+    description: 'User verification policy',
+    example: 'preferred',
+    enum: ['required', 'discouraged', 'preferred'],
+  })
+  userVerification?: 'required' | 'discouraged' | 'preferred';
+
+  @ApiPropertyOptional({
+    example: AuthenticationExtensionsDto,
+    description: 'WebAuthn extensions',
+    type: AuthenticationExtensionsDto,
+  })
+  extensions?: AuthenticationExtensionsDto;
+}

src/user/user.controller.ts

@@ -22,13 +22,13 @@ import {
   ApiCreatedResponse,
   ApiForbiddenResponse,
   ApiInternalServerErrorResponse,
+  ApiNotFoundResponse,
   ApiOkResponse,
   ApiOperation,
   ApiTags,
   ApiUnauthorizedResponse,
 } from '@nestjs/swagger';
 import { User } from '@prisma/client';
-import { PublicKeyCredentialRequestOptionsJSON } from '@simplewebauthn/types';
 import { GetUser } from 'src/auth/decorator/getUser.decorator';
 import { UserGuard } from 'src/auth/guard/auth.guard';
 
@@ -40,6 +40,7 @@ import {
   VerifyPasskeyRegistrationDto,
 } from './dto/req.dto';
 import {
+  PasskeyOptionResDto,
   UpdateUserPictureResDto,
   UserConsentListResDto,
   UserConsentResDto,
@@ -190,17 +191,27 @@ export class UserController {
     summary: 'register the passkey',
     description: '패스키를 등록을 위한 challenge를 발급합니다.',
   })
+  @ApiOkResponse({
+    description: 'success',
+    type: PasskeyOptionResDto,
+  })
+  @ApiNotFoundResponse({ description: 'Email is not found' })
+  @ApiInternalServerErrorResponse({ description: 'server error' })
   @Post('passkey')
   async registerOptions(
     @Body() { email }: IssueUserSecretDto,
-  ): Promise<PublicKeyCredentialRequestOptionsJSON> {
+  ): Promise<PasskeyOptionResDto> {
     return await this.userService.registerOptions(email);
   }
 
   @ApiOperation({
     summary: 'verify the registration options',
     description: '패스키 등록합니다.',
   })
+  @ApiOkResponse({ description: 'success', type: Boolean })
+  @ApiUnauthorizedResponse({ description: 'Response is invalid' })
+  @ApiNotFoundResponse({ description: 'Email is not found' })
+  @ApiInternalServerErrorResponse({ description: 'server error' })
   @Post('passkey/verify')
   async verifyRegistration(
     @Body() { email, registrationResponse }: VerifyPasskeyRegistrationDto,