docs(openapi): add descriptions to OpenAPI specification (#25185)

* faces

* add openapi descriptions

* remove dto descriptions

* gen openapi

* dtos

* fix dtos

* fix more

* fix build

* more

* complete dtos

* descriptions on rebase

* gen rebase

* revert correct integer type conversion

* gen after revert

* revert correct nullables

* regen after revert

* actually incorrect adding default here

* revert correct number type conversion

* regen after revert

* revert nullable usage

* regen fully

* readd some comments

* one more

* one more

* use enum

* add missing

* add missing controllers

* add missing dtos

* complete it

* more

* describe global key and slug

* add remaining body and param descriptions

* lint and format

* cleanup

* response and schema descriptions

* test patch according to suggestion

* revert added api response objects

* revert added api body objects

* revert added api param object

* revert added api query objects

* revert reorganized http code objects

* revert reorganize ApiOkResponse objects

* revert added api response objects (2)

* revert added api tag object

* revert added api schema objects

* migrate missing asset.dto.ts

* regenerate openapi builds

* delete generated mustache files

* remove descriptions from properties that are schemas

* lint

* revert nullable type changes

* revert int/num type changes

* remove explicit default

* readd comment

* lint

* pr fixes

* last bits and pieces

* lint and format

* chore: remove rejected patches

* fix: deleting asset from asset-viewer on search results (#25596)

* fix: escape handling in search asset viewer (#25621)

* fix: correctly show owner in album options modal (#25618)

* fix: validation issues

* fix: validation issues

---------

Co-authored-by: Jason Rasmussen <jason@rasm.me>
Co-authored-by: Min Idzelis <min123@gmail.com>
Co-authored-by: Daniel Dietzler <36593685+danieldietzler@users.noreply.github.com>
Co-authored-by: Paul Makles <me@insrt.uk>

server/src/dtos/auth.dto.ts

@@ -1,4 +1,4 @@
-import { ApiProperty } from '@nestjs/swagger';
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
 import { Transform } from 'class-transformer';
 import { IsEmail, IsNotEmpty, IsString, MinLength } from 'class-validator';
 import { AuthApiKey, AuthSession, AuthSharedLink, AuthUser, UserAdmin } from 'src/database';
@@ -12,34 +12,46 @@ export type CookieResponse = {
 };
 
 export class AuthDto {
+  @ApiProperty({ description: 'Authenticated user' })
   user!: AuthUser;
 
+  @ApiPropertyOptional({ description: 'API key (if authenticated via API key)' })
   apiKey?: AuthApiKey;
+  @ApiPropertyOptional({ description: 'Shared link (if authenticated via shared link)' })
   sharedLink?: AuthSharedLink;
+  @ApiPropertyOptional({ description: 'Session (if authenticated via session)' })
   session?: AuthSession;
 }
 
 export class LoginCredentialDto {
+  @ApiProperty({ example: 'testuser@email.com', description: 'User email' })
   @IsEmail({ require_tld: false })
   @Transform(toEmail)
   @IsNotEmpty()
-  @ApiProperty({ example: 'testuser@email.com' })
   email!: string;
 
+  @ApiProperty({ example: 'password', description: 'User password' })
   @IsString()
   @IsNotEmpty()
-  @ApiProperty({ example: 'password' })
   password!: string;
 }
 
 export class LoginResponseDto {
+  @ApiProperty({ description: 'Access token' })
   accessToken!: string;
+  @ApiProperty({ description: 'User ID' })
   userId!: string;
+  @ApiProperty({ description: 'User email' })
   userEmail!: string;
+  @ApiProperty({ description: 'User name' })
   name!: string;
+  @ApiProperty({ description: 'Profile image path' })
   profileImagePath!: string;
+  @ApiProperty({ description: 'Is admin user' })
   isAdmin!: boolean;
+  @ApiProperty({ description: 'Should change password' })
   shouldChangePassword!: boolean;
+  @ApiProperty({ description: 'Is onboarded' })
   isOnboarded!: boolean;
 }
 
@@ -61,42 +73,47 @@ export function mapLoginResponse(entity: UserAdmin, accessToken: string): LoginR
 }
 
 export class LogoutResponseDto {
+  @ApiProperty({ description: 'Logout successful' })
   successful!: boolean;
+  @ApiProperty({ description: 'Redirect URI' })
   redirectUri!: string;
 }
 
 export class SignUpDto extends LoginCredentialDto {
+  @ApiProperty({ example: 'Admin', description: 'User name' })
   @IsString()
   @IsNotEmpty()
-  @ApiProperty({ example: 'Admin' })
   name!: string;
 }
 
 export class ChangePasswordDto {
+  @ApiProperty({ example: 'password', description: 'Current password' })
   @IsString()
   @IsNotEmpty()
-  @ApiProperty({ example: 'password' })
   password!: string;
 
+  @ApiProperty({ example: 'password', description: 'New password (min 8 characters)' })
   @IsString()
   @IsNotEmpty()
   @MinLength(8)
-  @ApiProperty({ example: 'password' })
   newPassword!: string;
 
-  @ValidateBoolean({ optional: true, default: false })
+  @ValidateBoolean({ optional: true, default: false, description: 'Invalidate all other sessions' })
   invalidateSessions?: boolean;
 }
 
 export class PinCodeSetupDto {
+  @ApiProperty({ description: 'PIN code (4-6 digits)' })
   @PinCode()
   pinCode!: string;
 }
 
 export class PinCodeResetDto {
+  @ApiPropertyOptional({ description: 'New PIN code (4-6 digits)' })
   @PinCode({ optional: true })
   pinCode?: string;
 
+  @ApiPropertyOptional({ description: 'User password (required if PIN code is not provided)' })
   @Optional()
   @IsString()
   @IsNotEmpty()
@@ -106,51 +123,64 @@ export class PinCodeResetDto {
 export class SessionUnlockDto extends PinCodeResetDto {}
 
 export class PinCodeChangeDto extends PinCodeResetDto {
+  @ApiProperty({ description: 'New PIN code (4-6 digits)' })
   @PinCode()
   newPinCode!: string;
 }
 
 export class ValidateAccessTokenResponseDto {
+  @ApiProperty({ description: 'Authentication status' })
   authStatus!: boolean;
 }
 
 export class OAuthCallbackDto {
+  @ApiProperty({ description: 'OAuth callback URL' })
   @IsNotEmpty()
   @IsString()
-  @ApiProperty()
   url!: string;
 
+  @ApiPropertyOptional({ description: 'OAuth state parameter' })
   @Optional()
   @IsString()
   state?: string;
 
+  @ApiPropertyOptional({ description: 'OAuth code verifier (PKCE)' })
   @Optional()
   @IsString()
   codeVerifier?: string;
 }
 
 export class OAuthConfigDto {
+  @ApiProperty({ description: 'OAuth redirect URI' })
   @IsNotEmpty()
   @IsString()
   redirectUri!: string;
 
+  @ApiPropertyOptional({ description: 'OAuth state parameter' })
   @Optional()
   @IsString()
   state?: string;
 
+  @ApiPropertyOptional({ description: 'OAuth code challenge (PKCE)' })
   @Optional()
   @IsString()
   codeChallenge?: string;
 }
 
 export class OAuthAuthorizeResponseDto {
+  @ApiProperty({ description: 'OAuth authorization URL' })
   url!: string;
 }
 
 export class AuthStatusResponseDto {
+  @ApiProperty({ description: 'Has PIN code set' })
   pinCode!: boolean;
+  @ApiProperty({ description: 'Has password set' })
   password!: boolean;
+  @ApiProperty({ description: 'Is elevated session' })
   isElevated!: boolean;
+  @ApiPropertyOptional({ description: 'Session expiration date' })
   expiresAt?: string;
+  @ApiPropertyOptional({ description: 'PIN expiration date' })
   pinExpiresAt?: string;
 }