feat: endpoint descriptions (#23813)

server/src/controllers/activity.controller.ts

@@ -1,5 +1,5 @@
 import { Body, Controller, Delete, Get, HttpCode, HttpStatus, Param, Post, Query, Res } from '@nestjs/common';
-import { ApiTags } from '@nestjs/swagger';
+import { ApiOperation, ApiTags } from '@nestjs/swagger';
 import { Response } from 'express';
 import {
   ActivityCreateDto,
@@ -9,24 +9,33 @@ import {
   ActivityStatisticsResponseDto,
 } from 'src/dtos/activity.dto';
 import { AuthDto } from 'src/dtos/auth.dto';
-import { Permission } from 'src/enum';
+import { ApiTag, Permission } from 'src/enum';
 import { Auth, Authenticated } from 'src/middleware/auth.guard';
 import { ActivityService } from 'src/services/activity.service';
 import { UUIDParamDto } from 'src/validation';
 
-@ApiTags('Activities')
+@ApiTags(ApiTag.Activities)
 @Controller('activities')
 export class ActivityController {
   constructor(private service: ActivityService) {}
 
   @Get()
   @Authenticated({ permission: Permission.ActivityRead })
+  @ApiOperation({
+    summary: 'List all activities',
+    description:
+      'Returns a list of activities for the selected asset or album. The activities are returned in sorted order, with the oldest activities appearing first.',
+  })
   getActivities(@Auth() auth: AuthDto, @Query() dto: ActivitySearchDto): Promise<ActivityResponseDto[]> {
     return this.service.getAll(auth, dto);
   }
 
   @Post()
   @Authenticated({ permission: Permission.ActivityCreate })
+  @ApiOperation({
+    summary: 'Create an activity',
+    description: 'Create a like or a comment for an album, or an asset in an album.',
+  })
   async createActivity(
     @Auth() auth: AuthDto,
     @Body() dto: ActivityCreateDto,
@@ -41,6 +50,10 @@ export class ActivityController {
 
   @Get('statistics')
   @Authenticated({ permission: Permission.ActivityStatistics })
+  @ApiOperation({
+    summary: 'Retrieve activity statistics',
+    description: 'Returns the number of likes and comments for a given album or asset in an album.',
+  })
   getActivityStatistics(@Auth() auth: AuthDto, @Query() dto: ActivityDto): Promise<ActivityStatisticsResponseDto> {
     return this.service.getStatistics(auth, dto);
   }
@@ -48,6 +61,10 @@ export class ActivityController {
   @Delete(':id')
   @Authenticated({ permission: Permission.ActivityDelete })
   @HttpCode(HttpStatus.NO_CONTENT)
+  @ApiOperation({
+    summary: 'Delete an activity',
+    description: 'Removes a like or comment from a given album or asset in an album.',
+  })
   deleteActivity(@Auth() auth: AuthDto, @Param() { id }: UUIDParamDto): Promise<void> {
     return this.service.delete(auth, id);
   }