Merge pull request #557 from Alt-Org/docs/move-swagger-to-code-556

Moved swagger definitions from file to code

Author: MikhailDeriabin

src/auth/auth.controller.ts

@@ -5,6 +5,9 @@ import { ThrowAuthErrorIfFound } from './decorator/ThrowAuthErrorIfFound.decorat
 import { NoAuth } from './decorator/NoAuth.decorator';
 import { AUTH_SERVICE } from './constant';
 import BoxAuthService from './box/BoxAuthService';
+import ApiResponseDescription from '../common/swagger/response/ApiResponseDescription';
+import { ModelName } from '../common/enum/modelName.enum';
+import { ProfileDto } from '../profile/dto/profile.dto';
 
 @NoAuth()
 @Controller('auth')
@@ -14,6 +17,21 @@ export class AuthController {
     private readonly authService: AuthService | BoxAuthService,
   ) {}
 
+  /**
+   * Log in to the system.
+   *
+   * @remarks After the profile with player was created, the user can log in to the system and get a JWT token to access resources.
+   *
+   * If the user provides the correct credentials, the access token will be returned, which should be used as a Bearer token in the Authorization header.
+   */
+  @ApiResponseDescription({
+    success: {
+      status: 201,
+      modelName: ModelName.CLAN,
+      type: ProfileDto,
+    },
+    errors: [400, 401],
+  })
   @Post('/signIn')
   @ThrowAuthErrorIfFound()
   public signIn(@Body() body: SignInDto) {

src/auth/dto/signIn.dto.ts

@@ -3,9 +3,19 @@ import AddType from '../../common/base/decorator/AddType.decorator';
 
 @AddType('SignInDto')
 export class SignInDto {
+  /**
+   * Unique username used by the player to sign in
+   *
+   * @example "DragonSlayer42"
+   */
   @IsString()
   username: string;
 
+  /**
+   * Password for player authentication
+   *
+   * @example "myStrongP@ssw0rd"
+   */
   @IsString()
   password: string;
 }

src/box/box.controller.ts

@@ -31,6 +31,8 @@ import { BoxUser } from './auth/BoxUser';
 import { LoggedUser } from '../common/decorator/param/LoggedUser.decorator';
 import { BoxAuthGuard } from './auth/boxAuth.guard';
 import SessionStarterService from './sessionStarter/sessionStarter.service';
+import ApiResponseDescription from '../common/swagger/response/ApiResponseDescription';
+import { BoxDto } from './dto/box.dto';
 
 @Controller('box')
 @UseGuards(BoxAuthGuard)
@@ -42,6 +44,24 @@ export class BoxController {
     private readonly sessionStarter: SessionStarterService,
   ) {}
 
+  /**
+   * Claim tester account.
+   *
+   * @remarks Tester can claim his/her account for the testing box.
+   *
+   * Notice that the tester should know the shared testers password in order to be able to clain the account.
+   * This password is available after the group admin has started the session.
+   *
+   * Notice that the endpoint should be called only from browser, since a cookie should be added by the API
+   */
+  @ApiResponseDescription({
+    success: {
+      status: 200,
+      type: ClaimAccountResponseDto,
+    },
+    errors: [400, 403, 404],
+    hasAuth: false,
+  })
   @NoAuth()
   @Get('claim-account')
   @UniformResponse(undefined, ClaimAccountResponseDto)
@@ -65,6 +85,22 @@ export class BoxController {
     return res.send(data);
   }
 
+  /**
+   * Create a testing box.
+   *
+   * @remarks Create a testing box.
+   *
+   * Notice that in order t0 create the testing box a group admin password need to be obtained from backend team
+   */
+  @ApiResponseDescription({
+    success: {
+      status: 201,
+      dto: CreatedBoxDto,
+      modelName: ModelName.BOX,
+    },
+    errors: [400, 404],
+    hasAuth: false,
+  })
   @NoAuth()
   @Post()
   @UniformResponse(ModelName.BOX, CreatedBoxDto)
@@ -81,6 +117,21 @@ export class BoxController {
     return [{ ...createdBox, accessToken: groupAdminAccessToken }, null];
   }
 
+  /**
+   * Reset testing box.
+   *
+   * @remarks Reset testing box data, which means removing all the data created during the testing session and returning the box state to the PREPARING stage.
+   * For more information refer to the testing box documentation.
+   *
+   * Notice that only box admin can do the action.
+   */
+  @ApiResponseDescription({
+    success: {
+      dto: CreatedBoxDto,
+      modelName: ModelName.BOX,
+    },
+    errors: [401, 403, 404],
+  })
   @Put('reset')
   @UniformResponse(ModelName.BOX)
   @IsGroupAdmin()
@@ -102,13 +153,41 @@ export class BoxController {
     return [{ ...createdBox, accessToken: groupAdminAccessToken }, null];
   }
 
+  /**
+   * Delete box data.
+   *
+   * @remarks Delete box data associated with the logged-in user.
+   *
+   * Notice that the box can be removed only by the box admin.
+   */
+  @ApiResponseDescription({
+    success: {
+      status: 204,
+    },
+    errors: [400, 404],
+  })
   @Delete()
   @IsGroupAdmin()
   @UniformResponse()
   async deleteBoxAndAdmin(@LoggedUser() user: BoxUser) {
     return await this.service.deleteBox(user.box_id);
   }
 
+  /**
+   * Start testing session
+   *
+   * @remarks Endpoint for starting testing session.
+   *
+   * Notice that only box admin can start a testing session.
+   *
+   * Notice that the minimum box data should be initialized at the moment of starting of testing session. That data is at least 2 tester accounts added.
+   */
+  @ApiResponseDescription({
+    success: {
+      status: 204,
+    },
+    errors: [401, 403, 404],
+  })
   @Post('/start')
   @UniformResponse(ModelName.BOX)
   @IsGroupAdmin()
@@ -117,6 +196,19 @@ export class BoxController {
     if (errors) return [null, errors];
   }
 
+  /**
+   * Get box by _id, For time of development only
+   *
+   * @remarks Endpoint for getting box data by its _id
+   */
+  @ApiResponseDescription({
+    success: {
+      dto: BoxDto,
+      modelName: ModelName.BOX,
+    },
+    errors: [404],
+    hasAuth: false,
+  })
   //For time of development only
   @NoAuth()
   @Get('/:_id')
@@ -129,6 +221,18 @@ export class BoxController {
     return this.service.readOneById(param._id, { includeRefs });
   }
 
+  /**
+   * Delete box by _id
+   *
+   * @remarks Endpoint for deleting a box by _id
+   */
+  @ApiResponseDescription({
+    success: {
+      status: 204,
+    },
+    errors: [404],
+    hasAuth: false,
+  })
   //For time of development only
   @NoAuth()
   @Delete('/:_id')

src/box/box.service.ts

@@ -170,7 +170,7 @@ export class BoxService {
   private getTesterAccount(box: BoxDto): Tester {
     const account = box.testers.find((tester) => {
       return tester.isClaimed !== true;
-    });
+    }) as unknown as Tester;
     if (!account) {
       throw new ServiceError({
         reason: SEReason.NOT_FOUND,

src/box/dailyTask/dailyTask.controller.ts

@@ -13,14 +13,32 @@ import { APIError } from '../../common/controller/APIError';
 import { APIErrorReason } from '../../common/controller/APIErrorReason';
 import BoxAuthHandler from '../auth/BoxAuthHandler';
 import { IsGroupAdmin } from '../auth/decorator/IsGroupAdmin';
+import ApiResponseDescription from '../../common/swagger/response/ApiResponseDescription';
+import SwaggerTags from '../../common/swagger/tags/SwaggerTags.decorator';
 
+@SwaggerTags('Box')
 @Controller('/box/dailyTask')
 export class DailyTaskController {
   constructor(
     private readonly taskService: DailyTaskService,
     private readonly boxAuthHandler: BoxAuthHandler,
   ) {}
 
+  /**
+   * Add a daily task to box
+   *
+   * @remarks Add a daily task to array of predefined daily tasks.
+   *
+   * Notice that the logged-in player has to be a group admin
+   */
+  @ApiResponseDescription({
+    success: {
+      status: 201,
+      dto: PredefinedDailyTaskDto,
+      modelName: ModelName.DAILY_TASK,
+    },
+    errors: [400, 401, 403, 404],
+  })
   @Post()
   @IsGroupAdmin()
   @UniformResponse(ModelName.DAILY_TASK, PredefinedDailyTaskDto)
@@ -31,6 +49,22 @@ export class DailyTaskController {
     return this.taskService.addOne(user.box_id, body);
   }
 
+  /**
+   * Add multiple daily tasks
+   *
+   * @remarks Add multiple daily tasks at once to daily tasks array of the box.
+   *
+   * Notice that only group admin can add the tasks.
+   */
+  @ApiResponseDescription({
+    success: {
+      status: 201,
+      dto: PredefinedDailyTaskDto,
+      modelName: ModelName.DAILY_TASK,
+      returnsArray: true,
+    },
+    errors: [400, 401, 403, 404],
+  })
   @Post('/multiple')
   @IsGroupAdmin()
   @UniformResponse(ModelName.DAILY_TASK, PredefinedDailyTaskDto)
@@ -55,6 +89,19 @@ export class DailyTaskController {
     return this.taskService.addMultiple(user.box_id, body);
   }
 
+  /**
+   * Update box daily task
+   *
+   * @remarks Update a predefined daily task of a box by its _id.
+   *
+   * Notice that only group admin can update the tasks
+   */
+  @ApiResponseDescription({
+    success: {
+      status: 204,
+    },
+    errors: [400, 401, 403, 404],
+  })
   @Put()
   @IsGroupAdmin()
   @UniformResponse(ModelName.DAILY_TASK)
@@ -69,6 +116,19 @@ export class DailyTaskController {
     if (errors) return [null, errors];
   }
 
+  /**
+   * Delete box daily task by _id
+   *
+   * @remarks Delete daily task from predefined daily tasks array of the box.
+   *
+   * Notice that only group admin can delete the tasks
+   */
+  @ApiResponseDescription({
+    success: {
+      status: 204,
+    },
+    errors: [400, 401, 403, 404],
+  })
   @Delete('/:_id')
   @IsGroupAdmin()
   @UniformResponse(ModelName.DAILY_TASK)

src/box/dailyTask/dto/createPredefinedDailyTask.dto.ts

@@ -2,21 +2,51 @@ import { IsEnum, IsNumber, IsString } from 'class-validator';
 import { ServerTaskName } from '../../../dailyTasks/enum/serverTaskName.enum';
 
 export class CreatePredefinedDailyTaskDto {
+  /**
+   * Type of the predefined server task (e.g., collect items, win battles)
+   *
+   * @example "write_chat_message"
+   */
   @IsEnum(ServerTaskName)
   type: ServerTaskName;
 
+  /**
+   * Human-readable title of the task shown to players
+   *
+   * @example "Collect 10 Soul Orbs"
+   */
   @IsString()
   title: string;
 
+  /**
+   * Required amount to complete the task (e.g., collect 10 orbs)
+   *
+   * @example 10
+   */
   @IsNumber()
   amount: number;
 
+  /**
+   * Points awarded upon task completion
+   *
+   * @example 50
+   */
   @IsNumber()
   points: number;
 
+  /**
+   * In-game currency reward for completing the task
+   *
+   * @example 100
+   */
   @IsNumber()
   coins: number;
 
+  /**
+   * Time limit in minutes to complete the task (0 = no limit)
+   *
+   * @example 30
+   */
   @IsNumber()
   timeLimitMinutes: number;
 }