feat: endpoint descriptions (#23813)

server/src/controllers/shared-link.controller.ts

@@ -13,7 +13,7 @@ import {
   Req,
   Res,
 } from '@nestjs/common';
-import { ApiTags } from '@nestjs/swagger';
+import { ApiOperation, ApiTags } from '@nestjs/swagger';
 import { Request, Response } from 'express';
 import { AssetIdsResponseDto } from 'src/dtos/asset-ids.response.dto';
 import { AssetIdsDto } from 'src/dtos/asset.dto';
@@ -25,26 +25,34 @@ import {
   SharedLinkResponseDto,
   SharedLinkSearchDto,
 } from 'src/dtos/shared-link.dto';
-import { ImmichCookie, Permission } from 'src/enum';
+import { ApiTag, ImmichCookie, Permission } from 'src/enum';
 import { Auth, Authenticated, GetLoginDetails } from 'src/middleware/auth.guard';
 import { LoginDetails } from 'src/services/auth.service';
 import { SharedLinkService } from 'src/services/shared-link.service';
 import { respondWithCookie } from 'src/utils/response';
 import { UUIDParamDto } from 'src/validation';
 
-@ApiTags('Shared Links')
+@ApiTags(ApiTag.SharedLinks)
 @Controller('shared-links')
 export class SharedLinkController {
   constructor(private service: SharedLinkService) {}
 
   @Get()
   @Authenticated({ permission: Permission.SharedLinkRead })
+  @ApiOperation({
+    summary: 'Retrieve all shared links',
+    description: 'Retrieve a list of all shared links.',
+  })
   getAllSharedLinks(@Auth() auth: AuthDto, @Query() dto: SharedLinkSearchDto): Promise<SharedLinkResponseDto[]> {
     return this.service.getAll(auth, dto);
   }
 
   @Get('me')
   @Authenticated({ sharedLink: true })
+  @ApiOperation({
+    summary: 'Retrieve current shared link',
+    description: 'Retrieve the current shared link associated with authentication method.',
+  })
   async getMySharedLink(
     @Auth() auth: AuthDto,
     @Query() dto: SharedLinkPasswordDto,
@@ -65,18 +73,30 @@ export class SharedLinkController {
 
   @Get(':id')
   @Authenticated({ permission: Permission.SharedLinkRead })
+  @ApiOperation({
+    summary: 'Retrieve a shared link',
+    description: 'Retrieve a specific shared link by its ID.',
+  })
   getSharedLinkById(@Auth() auth: AuthDto, @Param() { id }: UUIDParamDto): Promise<SharedLinkResponseDto> {
     return this.service.get(auth, id);
   }
 
   @Post()
   @Authenticated({ permission: Permission.SharedLinkCreate })
+  @ApiOperation({
+    summary: 'Create a shared link',
+    description: 'Create a new shared link.',
+  })
   createSharedLink(@Auth() auth: AuthDto, @Body() dto: SharedLinkCreateDto) {
     return this.service.create(auth, dto);
   }
 
   @Patch(':id')
   @Authenticated({ permission: Permission.SharedLinkUpdate })
+  @ApiOperation({
+    summary: 'Update a shared link',
+    description: 'Update an existing shared link by its ID.',
+  })
   updateSharedLink(
     @Auth() auth: AuthDto,
     @Param() { id }: UUIDParamDto,
@@ -88,12 +108,21 @@ export class SharedLinkController {
   @Delete(':id')
   @Authenticated({ permission: Permission.SharedLinkDelete })
   @HttpCode(HttpStatus.NO_CONTENT)
+  @ApiOperation({
+    summary: 'Delete a shared link',
+    description: 'Delete a specific shared link by its ID.',
+  })
   removeSharedLink(@Auth() auth: AuthDto, @Param() { id }: UUIDParamDto): Promise<void> {
     return this.service.remove(auth, id);
   }
 
   @Put(':id/assets')
   @Authenticated({ sharedLink: true })
+  @ApiOperation({
+    summary: 'Add assets to a shared link',
+    description:
+      'Add assets to a specific shared link by its ID. This endpoint is only relevant for shared link of type individual.',
+  })
   addSharedLinkAssets(
     @Auth() auth: AuthDto,
     @Param() { id }: UUIDParamDto,
@@ -104,6 +133,11 @@ export class SharedLinkController {
 
   @Delete(':id/assets')
   @Authenticated({ sharedLink: true })
+  @ApiOperation({
+    summary: 'Remove assets from a shared link',
+    description:
+      'Remove assets from a specific shared link by its ID. This endpoint is only relevant for shared link of type individual.',
+  })
   removeSharedLinkAssets(
     @Auth() auth: AuthDto,
     @Param() { id }: UUIDParamDto,