feat: endpoint descriptions (#23813)

server/src/controllers/asset-media.controller.ts

@@ -34,7 +34,7 @@ import {
   UploadFieldName,
 } from 'src/dtos/asset-media.dto';
 import { AuthDto } from 'src/dtos/auth.dto';
-import { ImmichHeader, Permission, RouteKey } from 'src/enum';
+import { ApiTag, ImmichHeader, Permission, RouteKey } from 'src/enum';
 import { AssetUploadInterceptor } from 'src/middleware/asset-upload.interceptor';
 import { Auth, Authenticated, FileResponse } from 'src/middleware/auth.guard';
 import { FileUploadInterceptor, getFiles } from 'src/middleware/file-upload.interceptor';
@@ -44,7 +44,7 @@ import { UploadFiles } from 'src/types';
 import { ImmichFileResponse, sendFile } from 'src/utils/file';
 import { FileNotEmptyValidator, UUIDParamDto } from 'src/validation';
 
-@ApiTags('Assets')
+@ApiTags(ApiTag.Assets)
 @Controller(RouteKey.Asset)
 export class AssetMediaController {
   constructor(
@@ -53,6 +53,7 @@ export class AssetMediaController {
   ) {}
 
   @Post()
+  @Authenticated({ permission: Permission.AssetUpload, sharedLink: true })
   @UseInterceptors(AssetUploadInterceptor, FileUploadInterceptor)
   @ApiConsumes('multipart/form-data')
   @ApiHeader({
@@ -61,7 +62,10 @@ export class AssetMediaController {
     required: false,
   })
   @ApiBody({ description: 'Asset Upload Information', type: AssetMediaCreateDto })
-  @Authenticated({ permission: Permission.AssetUpload, sharedLink: true })
+  @ApiOperation({
+    summary: 'Upload asset',
+    description: 'Uploads a new asset to the server.',
+  })
   async uploadAsset(
     @Auth() auth: AuthDto,
     @UploadedFiles(new ParseFilePipe({ validators: [new FileNotEmptyValidator(['assetData'])] })) files: UploadFiles,
@@ -81,6 +85,10 @@ export class AssetMediaController {
   @Get(':id/original')
   @FileResponse()
   @Authenticated({ permission: Permission.AssetDownload, sharedLink: true })
+  @ApiOperation({
+    summary: 'Download original asset',
+    description: 'Downloads the original file of the specified asset.',
+  })
   async downloadAsset(
     @Auth() auth: AuthDto,
     @Param() { id }: UUIDParamDto,
@@ -90,17 +98,14 @@ export class AssetMediaController {
     await sendFile(res, next, () => this.service.downloadOriginal(auth, id), this.logger);
   }
 
-  /**
-   *  Replace the asset with new file, without changing its id
-   */
   @Put(':id/original')
   @UseInterceptors(FileUploadInterceptor)
   @ApiConsumes('multipart/form-data')
   @EndpointLifecycle({
     addedAt: 'v1.106.0',
     deprecatedAt: 'v1.142.0',
-    summary: 'replaceAsset',
-    description: 'Replace the asset with new file, without changing its id',
+    summary: 'Replace asset',
+    description: 'Replace the asset with new file, without changing its id.',
   })
   @Authenticated({ permission: Permission.AssetReplace, sharedLink: true })
   async replaceAsset(
@@ -122,6 +127,10 @@ export class AssetMediaController {
   @Get(':id/thumbnail')
   @FileResponse()
   @Authenticated({ permission: Permission.AssetView, sharedLink: true })
+  @ApiOperation({
+    summary: 'View asset thumbnail',
+    description: 'Retrieve the thumbnail image for the specified asset.',
+  })
   async viewAsset(
     @Auth() auth: AuthDto,
     @Param() { id }: UUIDParamDto,
@@ -159,6 +168,10 @@ export class AssetMediaController {
   @Get(':id/video/playback')
   @FileResponse()
   @Authenticated({ permission: Permission.AssetView, sharedLink: true })
+  @ApiOperation({
+    summary: 'Play asset video',
+    description: 'Streams the video file for the specified asset. This endpoint also supports byte range requests.',
+  })
   async playAssetVideo(
     @Auth() auth: AuthDto,
     @Param() { id }: UUIDParamDto,
@@ -174,7 +187,7 @@ export class AssetMediaController {
   @Post('exist')
   @Authenticated()
   @ApiOperation({
-    summary: 'checkExistingAssets',
+    summary: 'Check existing assets',
     description: 'Checks if multiple assets exist on the server and returns all existing - used by background backup',
   })
   @HttpCode(HttpStatus.OK)
@@ -191,8 +204,8 @@ export class AssetMediaController {
   @Post('bulk-upload-check')
   @Authenticated({ permission: Permission.AssetUpload })
   @ApiOperation({
-    summary: 'checkBulkUpload',
-    description: 'Checks if assets exist by checksums',
+    summary: 'Check bulk upload',
+    description: 'Determine which assets have already been uploaded to the server based on their SHA1 checksums.',
   })
   @HttpCode(HttpStatus.OK)
   checkBulkUpload(