feat: endpoint descriptions (#23813)

server/src/controllers/oauth.controller.ts

@@ -1,5 +1,5 @@
 import { Body, Controller, Get, HttpCode, HttpStatus, Post, Redirect, Req, Res } from '@nestjs/common';
-import { ApiTags } from '@nestjs/swagger';
+import { ApiOperation, ApiTags } from '@nestjs/swagger';
 import { Request, Response } from 'express';
 import {
   AuthDto,
@@ -9,18 +9,23 @@ import {
   OAuthConfigDto,
 } from 'src/dtos/auth.dto';
 import { UserAdminResponseDto } from 'src/dtos/user.dto';
-import { AuthType, ImmichCookie } from 'src/enum';
+import { ApiTag, AuthType, ImmichCookie } from 'src/enum';
 import { Auth, Authenticated, GetLoginDetails } from 'src/middleware/auth.guard';
 import { AuthService, LoginDetails } from 'src/services/auth.service';
 import { respondWithCookie } from 'src/utils/response';
 
-@ApiTags('OAuth')
+@ApiTags(ApiTag.Authentication)
 @Controller('oauth')
 export class OAuthController {
   constructor(private service: AuthService) {}
 
   @Get('mobile-redirect')
   @Redirect()
+  @ApiOperation({
+    summary: 'Redirect OAuth to mobile',
+    description:
+      'Requests to this URL are automatically forwarded to the mobile app, and is used in some cases for OAuth redirecting.',
+  })
   redirectOAuthToMobile(@Req() request: Request) {
     return {
       url: this.service.getMobileRedirect(request.url),
@@ -29,6 +34,10 @@ export class OAuthController {
   }
 
   @Post('authorize')
+  @ApiOperation({
+    summary: 'Start OAuth',
+    description: 'Initiate the OAuth authorization process.',
+  })
   async startOAuth(
     @Body() dto: OAuthConfigDto,
     @Res({ passthrough: true }) res: Response,
@@ -49,6 +58,10 @@ export class OAuthController {
   }
 
   @Post('callback')
+  @ApiOperation({
+    summary: 'Finish OAuth',
+    description: 'Complete the OAuth authorization process by exchanging the authorization code for a session token.',
+  })
   async finishOAuth(
     @Req() request: Request,
     @Res({ passthrough: true }) res: Response,
@@ -71,6 +84,10 @@ export class OAuthController {
   @Post('link')
   @Authenticated()
   @HttpCode(HttpStatus.OK)
+  @ApiOperation({
+    summary: 'Link OAuth account',
+    description: 'Link an OAuth account to the authenticated user.',
+  })
   linkOAuthAccount(
     @Req() request: Request,
     @Auth() auth: AuthDto,
@@ -82,6 +99,10 @@ export class OAuthController {
   @Post('unlink')
   @Authenticated()
   @HttpCode(HttpStatus.OK)
+  @ApiOperation({
+    summary: 'Unlink OAuth account',
+    description: 'Unlink the OAuth account from the authenticated user.',
+  })
   unlinkOAuthAccount(@Auth() auth: AuthDto): Promise<UserAdminResponseDto> {
     return this.service.unlink(auth);
   }