optimize swagger annotation.

lxdao-official · Dec 11, 2024 · e1e2d2a · e1e2d2a
1 parent efc256c
commit e1e2d2a
Show file tree

Hide file tree

Showing 6 changed files with 133 additions and 71 deletions.
diff --git a/src/controller/pool.controller.ts b/src/controller/pool.controller.ts
@@ -6,6 +6,7 @@ import {
   PoolListQuery,
 } from '@core/type/doc/pool';
 import { Body, Controller, Get, Inject, Post, Query } from '@nestjs/common';
+import { ApiOperation } from '@nestjs/swagger';
 import { PoolService } from '@service/pool.service';
 
 @Controller('pool')
@@ -22,18 +23,26 @@ export class PoolController {
   }
 
   @Post('create')
+  @ApiOperation({ description: '创建激励池' })
   async createPool(@Body() body: CreatePoolBody) {
     const result = await this.poolService.createPool(body);
     return CoreApiResponse.success(result);
   }
 
   @Get('claimStatus')
+  @ApiOperation({
+    description:
+      '获取 project 下用户所有激励池的 claim 状态, 初始为 UNCLAIMED, claim 成功后更新为 CLAIMED',
+  })
   async getClaimStatus(@Query() query: ClaimStatusQuery) {
     const result = await this.poolService.getClaimStatus(query);
     return CoreApiResponse.success(result);
   }
 
   @Post('claim')
+  @ApiOperation({
+    description: 'project 下调用 pool 合约 claim 后, 更新 claim 状态',
+  })
   async claim(@Body() body: ClaimBody) {
     const result = await this.poolService.contributorClaim(body);
     return CoreApiResponse.success(result);

diff --git a/src/core/service/pool.service.ts b/src/core/service/pool.service.ts
@@ -135,7 +135,9 @@ export class PoolService {
       }
     }
 
-    return this.prisma.$transaction(fns);
+    await this.prisma.$transaction(fns);
+
+    return { id };
   }
 
   async contributorClaim(body: ClaimBody) {
@@ -181,5 +183,9 @@ export class PoolService {
         }),
       );
     });
+
+    return {
+      poolId,
+    };
   }
 }
diff --git a/src/core/type/doc/allocation.ts b/src/core/type/doc/allocation.ts
@@ -12,7 +12,10 @@ import {
 export class AllocationListQuery extends PaginateQuery {
   @IsNotEmpty()
   @IsString()
-  @ApiProperty({ type: 'string' })
+  @ApiProperty({
+    type: 'string',
+    description: 'project id(同时也是 project address)',
+  })
   projectId: string;
 
   // @IsOptional()
@@ -29,38 +32,51 @@ export class AllocationListQuery extends PaginateQuery {
 export class UpdateAllocationStatusBody extends AuthBody {
   @IsNotEmpty()
   @IsString()
-  @ApiProperty({ type: 'string' })
+  @ApiProperty({
+    type: 'string',
+    description:
+      'allocation 状态,有3个,分别是 INITIAL:初始,ATTESTED:经 EAS 创建成功, REVOKED: EAS 记录撤销(暂时用不到)',
+  })
   status: 'INITIAL' | 'ATTESTED' | 'REVOKED';
 
   @IsOptional()
   @IsString()
-  @ApiProperty({ type: 'string' })
+  @ApiProperty({ type: 'string', description: '经 EAS 创建成功后返回的 uid' })
   uId: string;
 }
 
 export class CreateAllocationBody extends AuthBody {
   @IsNotEmpty()
   @IsString()
-  @ApiProperty({ type: 'string' })
+  @ApiProperty({ type: 'string', description: 'allocation 标题' })
   title: string;
 
   @IsNotEmpty()
   @IsString()
-  @ApiProperty({ type: 'string' })
+  @ApiProperty({
+    type: 'string',
+    description: 'project id(同时也是 project address)',
+  })
   projectId: string;
 
   @ArrayNotEmpty()
   @IsArray()
-  @ApiProperty({ isArray: true })
+  @ApiProperty({ isArray: true, description: '贡献者钱包地址列表' })
   contributors: string[];
 
   @ArrayNotEmpty()
   @IsArray()
-  @ApiProperty({ isArray: true })
+  @ApiProperty({
+    isArray: true,
+    description: '贡献者分配 token 百分比列表,,精度为8位',
+  })
   ratios: number[];
 
   @ArrayNotEmpty()
   @IsArray()
-  @ApiProperty({ isArray: true })
+  @ApiProperty({
+    isArray: true,
+    description: '贡献者 claim 成功的 token 数量,精度以 token decimal为准',
+  })
   credits: string[];
 }
diff --git a/src/core/type/doc/auth.ts b/src/core/type/doc/auth.ts
@@ -1,19 +1,19 @@
-import { IsOptional, IsString } from 'class-validator';
 import { ApiProperty } from '@nestjs/swagger';
+import { IsOptional, IsString } from 'class-validator';
 
 export class AuthBody {
   @IsOptional()
   @IsString()
-  @ApiProperty({ type: 'string' })
+  @ApiProperty({ type: 'string', description: '暂时不用传' })
   signature?: string;
 
   @IsOptional()
   @IsString()
-  @ApiProperty({ type: 'string' })
+  @ApiProperty({ type: 'string', description: '当前用户id,' })
   operatorId?: string;
 
   @IsOptional()
   @IsString()
-  @ApiProperty({ type: 'string' })
+  @ApiProperty({ type: 'string', description: '当前用户钱包地址' })
   wallet?: string;
 }
diff --git a/src/core/type/doc/common.ts b/src/core/type/doc/common.ts
@@ -1,17 +1,17 @@
-import { IsNumber, IsOptional } from 'class-validator';
 import { ApiProperty } from '@nestjs/swagger';
 import { Type } from 'class-transformer';
+import { IsNumber, IsOptional } from 'class-validator';
 
 export class PaginateQuery {
   @IsOptional()
   @IsNumber()
   @Type(() => Number)
-  @ApiProperty({ type: 'number' })
+  @ApiProperty({ type: 'number', description: '当前页码,从 1 开始' })
   currentPage: number;
 
   @IsOptional()
   @IsNumber()
   @Type(() => Number)
-  @ApiProperty({ type: 'number' })
+  @ApiProperty({ type: 'number', description: '当前页记录数' })
   pageSize: number;
 }
diff --git a/src/core/type/doc/pool.ts b/src/core/type/doc/pool.ts
@@ -14,140 +14,171 @@ import {
 export class PoolListQuery extends PaginateQuery {
   @IsNotEmpty()
   @IsString()
-  @ApiProperty({ type: 'string' })
+  @ApiProperty({
+    type: 'string',
+    description: 'project id(同时也是 project address)',
+  })
   projectId: string;
 
   @IsOptional()
   @IsNumber()
   @Type(() => Number)
-  @ApiProperty({ type: 'number' })
+  @ApiProperty({ type: 'number', description: '筛选激励池创建起始时间' })
   endDateFrom?: number;
 
   @IsOptional()
   @IsNumber()
   @Type(() => Number)
-  @ApiProperty({ type: 'number' })
+  @ApiProperty({ type: 'number', description: '筛选激励池创建结束时间' })
   endDateTo?: number;
 }
 
 export class ClaimStatusQuery {
   @IsNotEmpty()
   @IsString()
-  @ApiProperty({ type: 'string' })
+  @ApiProperty({
+    type: 'string',
+    description: 'project id(同时也是 project address)',
+  })
   projectId: string;
 
   @IsNotEmpty()
   @IsString()
-  @ApiProperty({ type: 'string' })
+  @ApiProperty({ type: 'string', description: '要获取的钱包地址 claim 状态' })
   wallet: string;
-
-  // @ArrayNotEmpty()
-  // @IsArray()
-  // @ApiProperty({ isArray: true })
-  // pools: string[];
 }
 
 export class CreatePoolBody extends AuthBody {
   @IsNotEmpty()
   @IsString()
-  @ApiProperty({ type: 'string' })
+  @ApiProperty({ type: 'string', description: '经过 EAS 创建的 allocation id' })
   allocationId: string;
 
   @IsNotEmpty()
   @IsString()
-  @ApiProperty({ type: 'string' })
+  @ApiProperty({
+    type: 'string',
+    description: 'project id(同时也是 project address)',
+  })
   projectId: string;
 
   @IsNotEmpty()
   @IsString()
-  @ApiProperty({ type: 'string' })
+  @ApiProperty({
+    type: 'string',
+    description: '工厂合约创建 pool 后, 得到的 pool address',
+  })
   address: string;
 
   @IsNotEmpty()
   @IsString()
-  @ApiProperty({ type: 'string' })
+  @ApiProperty({ type: 'string', description: '创建 pool 的钱包地址' })
   creator: string;
 
   @IsOptional()
   @IsNumber()
   @Type(() => Number)
-  @ApiProperty({ type: 'number' })
+  @ApiProperty({
+    type: 'number',
+    description: '创建 pool 的时间锁, 格式为 unix 时间戳(秒)',
+  })
   lockDuration: number;
 
   @IsNotEmpty()
   @IsString()
-  @ApiProperty({ type: 'string' })
+  @ApiProperty({
+    type: 'string',
+    description:
+      '给 pool 注入资金的钱包地址(一般为多签), 同时也是拥有 refund 权限的钱包地址',
+  })
   depositor: string;
 
   @ArrayNotEmpty()
   @IsArray()
-  @ApiProperty({ isArray: true })
+  @ApiProperty({ isArray: true, description: '给批量钱包分配 token 集合' })
   tokens: PoolTokenBody[];
 }
 
 export class PoolTokenBody {
   @IsNotEmpty()
   @IsString()
-  @ApiProperty({ type: 'string' })
+  @ApiProperty({
+    type: 'string',
+    description: 'token 合约地址,如果分配 token 是原生代币, 地址为address(0)',
+  })
   token: string;
 
   @ArrayNotEmpty()
   @IsArray()
-  @ApiProperty({ isArray: true })
+  @ApiProperty({ isArray: true, description: '分配的钱包地址列表' })
   wallets: string[];
 
   @ArrayNotEmpty()
   @IsArray()
-  @ApiProperty({ isArray: true })
+  @ApiProperty({
+    isArray: true,
+    description: '给每个钱包分配的 token 数量,精度为 token 的 decimal',
+  })
   amounts: string[];
 
   @ArrayNotEmpty()
   @IsArray()
-  @ApiProperty({ isArray: true })
+  @ApiProperty({
+    isArray: true,
+    description: '给每个钱包分配 token 的百分比, 同 allocation,精度为8位',
+  })
   ratios: number[];
 }
 
-export class PoolTokenClaimStatusBody extends PoolTokenBody {
-  @IsNotEmpty()
-  @IsString()
-  @ApiProperty({ type: 'string' })
-  token: string;
-
-  @IsNumber()
-  @Type(() => Number)
-  ratio: number;
-
-  @IsNotEmpty()
-  @IsString()
-  @ApiProperty({ type: 'string' })
-  amount: string;
-
-  @IsNotEmpty()
-  @IsString()
-  @ApiProperty({ type: 'string' })
-  status: string;
-}
-
-export class PoolClaimStatusResponse {
-  @IsNotEmpty()
-  @IsString()
-  @ApiProperty({ type: 'string' })
-  poolId: string;
-
-  @ArrayNotEmpty()
-  @IsArray()
-  @ApiProperty({ isArray: true })
-  tokens: PoolTokenClaimStatusBody[];
-}
+// export class PoolTokenClaimStatusBody extends PoolTokenBody {
+//   @IsNotEmpty()
+//   @IsString()
+//   @ApiProperty({ type: 'string', description: '' })
+//   token: string;
+//
+//   @IsNumber()
+//   @Type(() => Number)
+//   @ApiProperty({ type: 'number', description: '' })
+//   ratio: number;
+//
+//   @IsNotEmpty()
+//   @IsString()
+//   @ApiProperty({ type: 'string', description: '' })
+//   amount: string;
+//
+//   @IsNotEmpty()
+//   @IsString()
+//   @ApiProperty({ type: 'string', description: '' })
+//   status: string;
+// }
+//
+// export class PoolClaimStatusResponse {
+//   @IsNotEmpty()
+//   @IsString()
+//   @ApiProperty({ type: 'string' })
+//   poolId: string;
+//
+//   @ApiProperty({
+//     type: 'object',
+//     additionalProperties: {
+//       type: 'array',
+//       items: { type: 'string' },
+//     },
+//   })
+//   tokens: PoolTokenClaimStatusBody[];
+// }
 
 export class ClaimBody extends AuthBody {
   @IsNotEmpty()
   @IsString()
-  @ApiProperty({ type: 'string' })
+  @ApiProperty({
+    type: 'string',
+    description: 'project id(同时也是 project address)',
+  })
   projectId: string;
 
   @IsNotEmpty()
   @IsString()
-  @ApiProperty({ type: 'string' })
+  @ApiProperty({ type: 'string', description: '激励池 id' })
   poolId: string;
 }