feat: endpoint descriptions (#23813)

server/src/controllers/auth.controller.ts

@@ -1,5 +1,5 @@
 import { Body, Controller, Delete, Get, HttpCode, HttpStatus, Post, Put, Req, Res } from '@nestjs/common';
-import { ApiTags } from '@nestjs/swagger';
+import { ApiOperation, ApiTags } from '@nestjs/swagger';
 import { Request, Response } from 'express';
 import {
   AuthDto,
@@ -16,17 +16,21 @@ import {
   ValidateAccessTokenResponseDto,
 } from 'src/dtos/auth.dto';
 import { UserAdminResponseDto } from 'src/dtos/user.dto';
-import { AuthType, ImmichCookie, Permission } from 'src/enum';
+import { ApiTag, AuthType, ImmichCookie, Permission } from 'src/enum';
 import { Auth, Authenticated, GetLoginDetails } from 'src/middleware/auth.guard';
 import { AuthService, LoginDetails } from 'src/services/auth.service';
 import { respondWithCookie, respondWithoutCookie } from 'src/utils/response';
 
-@ApiTags('Authentication')
+@ApiTags(ApiTag.Authentication)
 @Controller('auth')
 export class AuthController {
   constructor(private service: AuthService) {}
 
   @Post('login')
+  @ApiOperation({
+    summary: 'Login',
+    description: 'Login with username and password and receive a session token.',
+  })
   async login(
     @Res({ passthrough: true }) res: Response,
     @Body() loginCredential: LoginCredentialDto,
@@ -44,11 +48,19 @@ export class AuthController {
   }
 
   @Post('admin-sign-up')
+  @ApiOperation({
+    summary: 'Register admin',
+    description: 'Create the first admin user in the system.',
+  })
   signUpAdmin(@Body() dto: SignUpDto): Promise<UserAdminResponseDto> {
     return this.service.adminSignUp(dto);
   }
 
   @Post('validateToken')
+  @ApiOperation({
+    summary: 'Validate access token',
+    description: 'Validate the current authorization method is still valid.',
+  })
   @Authenticated({ permission: false })
   @HttpCode(HttpStatus.OK)
   validateAccessToken(): ValidateAccessTokenResponseDto {
@@ -58,6 +70,10 @@ export class AuthController {
   @Post('change-password')
   @Authenticated({ permission: Permission.AuthChangePassword })
   @HttpCode(HttpStatus.OK)
+  @ApiOperation({
+    summary: 'Change password',
+    description: 'Change the password of the current user.',
+  })
   changePassword(@Auth() auth: AuthDto, @Body() dto: ChangePasswordDto): Promise<UserAdminResponseDto> {
     return this.service.changePassword(auth, dto);
   }
@@ -65,6 +81,10 @@ export class AuthController {
   @Post('logout')
   @Authenticated()
   @HttpCode(HttpStatus.OK)
+  @ApiOperation({
+    summary: 'Logout',
+    description: 'Logout the current user and invalidate the session token.',
+  })
   async logout(
     @Req() request: Request,
     @Res({ passthrough: true }) res: Response,
@@ -82,6 +102,11 @@ export class AuthController {
 
   @Get('status')
   @Authenticated()
+  @ApiOperation({
+    summary: 'Retrieve auth status',
+    description:
+      'Get information about the current session, including whether the user has a password, and if the session can access locked assets.',
+  })
   getAuthStatus(@Auth() auth: AuthDto): Promise<AuthStatusResponseDto> {
     return this.service.getAuthStatus(auth);
   }
@@ -89,6 +114,10 @@ export class AuthController {
   @Post('pin-code')
   @Authenticated({ permission: Permission.PinCodeCreate })
   @HttpCode(HttpStatus.NO_CONTENT)
+  @ApiOperation({
+    summary: 'Setup pin code',
+    description: 'Setup a new pin code for the current user.',
+  })
   setupPinCode(@Auth() auth: AuthDto, @Body() dto: PinCodeSetupDto): Promise<void> {
     return this.service.setupPinCode(auth, dto);
   }
@@ -96,6 +125,10 @@ export class AuthController {
   @Put('pin-code')
   @Authenticated({ permission: Permission.PinCodeUpdate })
   @HttpCode(HttpStatus.NO_CONTENT)
+  @ApiOperation({
+    summary: 'Change pin code',
+    description: 'Change the pin code for the current user.',
+  })
   async changePinCode(@Auth() auth: AuthDto, @Body() dto: PinCodeChangeDto): Promise<void> {
     return this.service.changePinCode(auth, dto);
   }
@@ -103,6 +136,10 @@ export class AuthController {
   @Delete('pin-code')
   @Authenticated({ permission: Permission.PinCodeDelete })
   @HttpCode(HttpStatus.NO_CONTENT)
+  @ApiOperation({
+    summary: 'Reset pin code',
+    description: 'Reset the pin code for the current user by providing the account password',
+  })
   async resetPinCode(@Auth() auth: AuthDto, @Body() dto: PinCodeResetDto): Promise<void> {
     return this.service.resetPinCode(auth, dto);
   }
@@ -110,12 +147,20 @@ export class AuthController {
   @Post('session/unlock')
   @Authenticated()
   @HttpCode(HttpStatus.NO_CONTENT)
+  @ApiOperation({
+    summary: 'Unlock auth session',
+    description: 'Temporarily grant the session elevated access to locked assets by providing the correct PIN code.',
+  })
   async unlockAuthSession(@Auth() auth: AuthDto, @Body() dto: SessionUnlockDto): Promise<void> {
     return this.service.unlockSession(auth, dto);
   }
 
   @Post('session/lock')
   @Authenticated()
+  @ApiOperation({
+    summary: 'Lock auth session',
+    description: 'Remove elevated access to locked assets from the current session.',
+  })
   @HttpCode(HttpStatus.NO_CONTENT)
   async lockAuthSession(@Auth() auth: AuthDto): Promise<void> {
     return this.service.lockSession(auth);