feat: endpoint descriptions (#23813)

server/src/controllers/trash.controller.ts

@@ -1,13 +1,13 @@
 import { Body, Controller, HttpCode, HttpStatus, Post } from '@nestjs/common';
-import { ApiTags } from '@nestjs/swagger';
+import { ApiOperation, ApiTags } from '@nestjs/swagger';
 import { BulkIdsDto } from 'src/dtos/asset-ids.response.dto';
 import { AuthDto } from 'src/dtos/auth.dto';
 import { TrashResponseDto } from 'src/dtos/trash.dto';
-import { Permission } from 'src/enum';
+import { ApiTag, Permission } from 'src/enum';
 import { Auth, Authenticated } from 'src/middleware/auth.guard';
 import { TrashService } from 'src/services/trash.service';
 
-@ApiTags('Trash')
+@ApiTags(ApiTag.Trash)
 @Controller('trash')
 export class TrashController {
   constructor(private service: TrashService) {}
@@ -15,6 +15,10 @@ export class TrashController {
   @Post('empty')
   @Authenticated({ permission: Permission.AssetDelete })
   @HttpCode(HttpStatus.OK)
+  @ApiOperation({
+    summary: 'Empty trash',
+    description: 'Permanently delete all items in the trash.',
+  })
   emptyTrash(@Auth() auth: AuthDto): Promise<TrashResponseDto> {
     return this.service.empty(auth);
   }
@@ -22,6 +26,10 @@ export class TrashController {
   @Post('restore')
   @Authenticated({ permission: Permission.AssetDelete })
   @HttpCode(HttpStatus.OK)
+  @ApiOperation({
+    summary: 'Restore trash',
+    description: 'Restore all items in the trash.',
+  })
   restoreTrash(@Auth() auth: AuthDto): Promise<TrashResponseDto> {
     return this.service.restore(auth);
   }
@@ -29,6 +37,10 @@ export class TrashController {
   @Post('restore/assets')
   @Authenticated({ permission: Permission.AssetDelete })
   @HttpCode(HttpStatus.OK)
+  @ApiOperation({
+    summary: 'Restore assets',
+    description: 'Restore specific assets from the trash.',
+  })
   restoreAssets(@Auth() auth: AuthDto, @Body() dto: BulkIdsDto): Promise<TrashResponseDto> {
     return this.service.restoreAssets(auth, dto);
   }