fix(docs): move a few API doc comments to descriptions (#15381)

Previously, the comments were being used as the summaries, and thus were
displayed as the “title” of these endpoints

mobile/openapi/README.md

@@ -93,17 +93,17 @@ Class | Method | HTTP request | Description
 *AlbumsApi* | [**removeUserFromAlbum**](doc//AlbumsApi.md#removeuserfromalbum) | **DELETE** /albums/{id}/user/{userId} | 
 *AlbumsApi* | [**updateAlbumInfo**](doc//AlbumsApi.md#updatealbuminfo) | **PATCH** /albums/{id} | 
 *AlbumsApi* | [**updateAlbumUser**](doc//AlbumsApi.md#updatealbumuser) | **PUT** /albums/{id}/user/{userId} | 
-*AssetsApi* | [**checkBulkUpload**](doc//AssetsApi.md#checkbulkupload) | **POST** /assets/bulk-upload-check | Checks if assets exist by checksums
-*AssetsApi* | [**checkExistingAssets**](doc//AssetsApi.md#checkexistingassets) | **POST** /assets/exist | Checks if multiple assets exist on the server and returns all existing - used by background backup
+*AssetsApi* | [**checkBulkUpload**](doc//AssetsApi.md#checkbulkupload) | **POST** /assets/bulk-upload-check | checkBulkUpload
+*AssetsApi* | [**checkExistingAssets**](doc//AssetsApi.md#checkexistingassets) | **POST** /assets/exist | checkExistingAssets
 *AssetsApi* | [**deleteAssets**](doc//AssetsApi.md#deleteassets) | **DELETE** /assets | 
 *AssetsApi* | [**downloadAsset**](doc//AssetsApi.md#downloadasset) | **GET** /assets/{id}/original | 
-*AssetsApi* | [**getAllUserAssetsByDeviceId**](doc//AssetsApi.md#getalluserassetsbydeviceid) | **GET** /assets/device/{deviceId} | Get all asset of a device that are in the database, ID only.
+*AssetsApi* | [**getAllUserAssetsByDeviceId**](doc//AssetsApi.md#getalluserassetsbydeviceid) | **GET** /assets/device/{deviceId} | getAllUserAssetsByDeviceId
 *AssetsApi* | [**getAssetInfo**](doc//AssetsApi.md#getassetinfo) | **GET** /assets/{id} | 
 *AssetsApi* | [**getAssetStatistics**](doc//AssetsApi.md#getassetstatistics) | **GET** /assets/statistics | 
 *AssetsApi* | [**getMemoryLane**](doc//AssetsApi.md#getmemorylane) | **GET** /assets/memory-lane | 
 *AssetsApi* | [**getRandom**](doc//AssetsApi.md#getrandom) | **GET** /assets/random | 
 *AssetsApi* | [**playAssetVideo**](doc//AssetsApi.md#playassetvideo) | **GET** /assets/{id}/video/playback | 
-*AssetsApi* | [**replaceAsset**](doc//AssetsApi.md#replaceasset) | **PUT** /assets/{id}/original | Replace the asset with new file, without changing its id
+*AssetsApi* | [**replaceAsset**](doc//AssetsApi.md#replaceasset) | **PUT** /assets/{id}/original | replaceAsset
 *AssetsApi* | [**runAssetJobs**](doc//AssetsApi.md#runassetjobs) | **POST** /assets/jobs | 
 *AssetsApi* | [**updateAsset**](doc//AssetsApi.md#updateasset) | **PUT** /assets/{id} | 
 *AssetsApi* | [**updateAssets**](doc//AssetsApi.md#updateassets) | **PUT** /assets | 

mobile/openapi/lib/api/assets_api.dart

@@ -16,6 +16,8 @@ class AssetsApi {
 
   final ApiClient apiClient;
 
+  /// checkBulkUpload
+  ///
   /// Checks if assets exist by checksums
   ///
   /// Note: This method returns the HTTP [Response].
@@ -48,6 +50,8 @@ class AssetsApi {
     );
   }
 
+  /// checkBulkUpload
+  ///
   /// Checks if assets exist by checksums
   ///
   /// Parameters:
@@ -68,6 +72,8 @@ class AssetsApi {
     return null;
   }
 
+  /// checkExistingAssets
+  ///
   /// Checks if multiple assets exist on the server and returns all existing - used by background backup
   ///
   /// Note: This method returns the HTTP [Response].
@@ -100,6 +106,8 @@ class AssetsApi {
     );
   }
 
+  /// checkExistingAssets
+  ///
   /// Checks if multiple assets exist on the server and returns all existing - used by background backup
   ///
   /// Parameters:
@@ -215,6 +223,8 @@ class AssetsApi {
     return null;
   }
 
+  /// getAllUserAssetsByDeviceId
+  ///
   /// Get all asset of a device that are in the database, ID only.
   ///
   /// Note: This method returns the HTTP [Response].
@@ -248,6 +258,8 @@ class AssetsApi {
     );
   }
 
+  /// getAllUserAssetsByDeviceId
+  ///
   /// Get all asset of a device that are in the database, ID only.
   ///
   /// Parameters:
@@ -564,6 +576,8 @@ class AssetsApi {
     return null;
   }
 
+  /// replaceAsset
+  ///
   /// Replace the asset with new file, without changing its id
   ///
   /// Note: This method returns the HTTP [Response].
@@ -645,6 +659,8 @@ class AssetsApi {
     );
   }
 
+  /// replaceAsset
+  ///
   /// Replace the asset with new file, without changing its id
   ///
   /// Parameters:

open-api/immich-openapi-specs.json

@@ -1424,6 +1424,7 @@
     },
     "/assets/bulk-upload-check": {
       "post": {
+        "description": "Checks if assets exist by checksums",
         "operationId": "checkBulkUpload",
         "parameters": [],
         "requestBody": {
@@ -1459,7 +1460,7 @@
             "api_key": []
           }
         ],
-        "summary": "Checks if assets exist by checksums",
+        "summary": "checkBulkUpload",
         "tags": [
           "Assets"
         ]
@@ -1467,6 +1468,7 @@
     },
     "/assets/device/{deviceId}": {
       "get": {
+        "description": "Get all asset of a device that are in the database, ID only.",
         "operationId": "getAllUserAssetsByDeviceId",
         "parameters": [
           {
@@ -1504,7 +1506,7 @@
             "api_key": []
           }
         ],
-        "summary": "Get all asset of a device that are in the database, ID only.",
+        "summary": "getAllUserAssetsByDeviceId",
         "tags": [
           "Assets"
         ]
@@ -1512,6 +1514,7 @@
     },
     "/assets/exist": {
       "post": {
+        "description": "Checks if multiple assets exist on the server and returns all existing - used by background backup",
         "operationId": "checkExistingAssets",
         "parameters": [],
         "requestBody": {
@@ -1547,7 +1550,7 @@
             "api_key": []
           }
         ],
-        "summary": "Checks if multiple assets exist on the server and returns all existing - used by background backup",
+        "summary": "checkExistingAssets",
         "tags": [
           "Assets"
         ]
@@ -1903,6 +1906,7 @@
         ]
       },
       "put": {
+        "description": "Replace the asset with new file, without changing its id",
         "operationId": "replaceAsset",
         "parameters": [
           {
@@ -1956,7 +1960,7 @@
             "api_key": []
           }
         ],
-        "summary": "Replace the asset with new file, without changing its id",
+        "summary": "replaceAsset",
         "tags": [
           "Assets"
         ],

open-api/typescript-sdk/src/fetch-client.ts

@@ -1703,7 +1703,7 @@ export function updateAssets({ assetBulkUpdateDto }: {
     })));
 }
 /**
- * Checks if assets exist by checksums
+ * checkBulkUpload
  */
 export function checkBulkUpload({ assetBulkUploadCheckDto }: {
     assetBulkUploadCheckDto: AssetBulkUploadCheckDto;
@@ -1718,7 +1718,7 @@ export function checkBulkUpload({ assetBulkUploadCheckDto }: {
     })));
 }
 /**
- * Get all asset of a device that are in the database, ID only.
+ * getAllUserAssetsByDeviceId
  */
 export function getAllUserAssetsByDeviceId({ deviceId }: {
     deviceId: string;
@@ -1731,7 +1731,7 @@ export function getAllUserAssetsByDeviceId({ deviceId }: {
     }));
 }
 /**
- * Checks if multiple assets exist on the server and returns all existing - used by background backup
+ * checkExistingAssets
  */
 export function checkExistingAssets({ checkExistingAssetsDto }: {
     checkExistingAssetsDto: CheckExistingAssetsDto;
@@ -1839,7 +1839,7 @@ export function downloadAsset({ id, key }: {
     }));
 }
 /**
- * Replace the asset with new file, without changing its id
+ * replaceAsset
  */
 export function replaceAsset({ id, key, assetMediaReplaceDto }: {
     id: string;

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

@@ -14,7 +14,7 @@ import {
   UploadedFiles,
   UseInterceptors,
 } from '@nestjs/common';
-import { ApiBody, ApiConsumes, ApiHeader, ApiTags } from '@nestjs/swagger';
+import { ApiBody, ApiConsumes, ApiHeader, ApiOperation, ApiTags } from '@nestjs/swagger';
 import { NextFunction, Response } from 'express';
 import { EndpointLifecycle } from 'src/decorators';
 import {
@@ -94,6 +94,10 @@ export class AssetMediaController {
   @UseInterceptors(FileUploadInterceptor)
   @ApiConsumes('multipart/form-data')
   @EndpointLifecycle({ addedAt: 'v1.106.0' })
+  @ApiOperation({
+    summary: 'replaceAsset',
+    description: 'Replace the asset with new file, without changing its id',
+  })
   @Authenticated({ sharedLink: true })
   async replaceAsset(
     @Auth() auth: AuthDto,
@@ -141,6 +145,10 @@ export class AssetMediaController {
    */
   @Post('exist')
   @HttpCode(HttpStatus.OK)
+  @ApiOperation({
+    summary: 'checkExistingAssets',
+    description: 'Checks if multiple assets exist on the server and returns all existing - used by background backup',
+  })
   @Authenticated()
   checkExistingAssets(
     @Auth() auth: AuthDto,
@@ -154,6 +162,10 @@ export class AssetMediaController {
    */
   @Post('bulk-upload-check')
   @HttpCode(HttpStatus.OK)
+  @ApiOperation({
+    summary: 'checkBulkUpload',
+    description: 'Checks if assets exist by checksums',
+  })
   @Authenticated()
   checkBulkUpload(
     @Auth() auth: AuthDto,

server/src/controllers/asset.controller.ts

@@ -1,5 +1,5 @@
 import { Body, Controller, Delete, Get, HttpCode, HttpStatus, Param, Post, Put, Query } from '@nestjs/common';
-import { ApiTags } from '@nestjs/swagger';
+import { ApiOperation, ApiTags } from '@nestjs/swagger';
 import { EndpointLifecycle } from 'src/decorators';
 import { AssetResponseDto, MemoryLaneResponseDto } from 'src/dtos/asset-response.dto';
 import {
@@ -41,6 +41,10 @@ export class AssetController {
    * Get all asset of a device that are in the database, ID only.
    */
   @Get('/device/:deviceId')
+  @ApiOperation({
+    summary: 'getAllUserAssetsByDeviceId',
+    description: 'Get all asset of a device that are in the database, ID only.',
+  })
   @Authenticated()
   getAllUserAssetsByDeviceId(@Auth() auth: AuthDto, @Param() { deviceId }: DeviceIdDto) {
     return this.service.getUserAssetsByDeviceId(auth, deviceId);