feat: endpoint descriptions (#23813)

server/src/controllers/duplicate.controller.ts

@@ -1,20 +1,24 @@
 import { Body, Controller, Delete, Get, HttpCode, HttpStatus, Param } 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 { DuplicateResponseDto } from 'src/dtos/duplicate.dto';
-import { Permission } from 'src/enum';
+import { ApiTag, Permission } from 'src/enum';
 import { Auth, Authenticated } from 'src/middleware/auth.guard';
 import { DuplicateService } from 'src/services/duplicate.service';
 import { UUIDParamDto } from 'src/validation';
 
-@ApiTags('Duplicates')
+@ApiTags(ApiTag.Duplicates)
 @Controller('duplicates')
 export class DuplicateController {
   constructor(private service: DuplicateService) {}
 
   @Get()
   @Authenticated({ permission: Permission.DuplicateRead })
+  @ApiOperation({
+    summary: 'Retrieve duplicates',
+    description: 'Retrieve a list of duplicate assets available to the authenticated user.',
+  })
   getAssetDuplicates(@Auth() auth: AuthDto): Promise<DuplicateResponseDto[]> {
     return this.service.getDuplicates(auth);
   }
@@ -22,6 +26,10 @@ export class DuplicateController {
   @Delete()
   @Authenticated({ permission: Permission.DuplicateDelete })
   @HttpCode(HttpStatus.NO_CONTENT)
+  @ApiOperation({
+    summary: 'Delete duplicates',
+    description: 'Delete multiple duplicate assets specified by their IDs.',
+  })
   deleteDuplicates(@Auth() auth: AuthDto, @Body() dto: BulkIdsDto): Promise<void> {
     return this.service.deleteAll(auth, dto);
   }
@@ -29,6 +37,10 @@ export class DuplicateController {
   @Delete(':id')
   @Authenticated({ permission: Permission.DuplicateDelete })
   @HttpCode(HttpStatus.NO_CONTENT)
+  @ApiOperation({
+    summary: 'Delete a duplicate',
+    description: 'Delete a single duplicate asset specified by its ID.',
+  })
   deleteDuplicate(@Auth() auth: AuthDto, @Param() { id }: UUIDParamDto): Promise<void> {
     return this.service.delete(auth, id);
   }