From b4a4abbf51043c8c9fe216fe1299f6c7e2019b5f Mon Sep 17 00:00:00 2001 From: Ben Cochran Date: Wed, 29 Jan 2025 08:58:10 -0800 Subject: [PATCH] fix(docs): move a few API doc comments to descriptions (#15381) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Previously, the comments were being used as the summaries, and thus were displayed as the “title” of these endpoints --- mobile/openapi/README.md | 8 ++++---- mobile/openapi/lib/api/assets_api.dart | 16 ++++++++++++++++ open-api/immich-openapi-specs.json | 12 ++++++++---- open-api/typescript-sdk/src/fetch-client.ts | 8 ++++---- server/src/controllers/asset-media.controller.ts | 14 +++++++++++++- server/src/controllers/asset.controller.ts | 6 +++++- 6 files changed, 50 insertions(+), 14 deletions(-) diff --git a/mobile/openapi/README.md b/mobile/openapi/README.md index 01ced65598..2ad316beff 100644 --- a/mobile/openapi/README.md +++ b/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 | diff --git a/mobile/openapi/lib/api/assets_api.dart b/mobile/openapi/lib/api/assets_api.dart index fd89986980..e7272d094c 100644 --- a/mobile/openapi/lib/api/assets_api.dart +++ b/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: diff --git a/open-api/immich-openapi-specs.json b/open-api/immich-openapi-specs.json index 351d865608..d70146fc24 100644 --- a/open-api/immich-openapi-specs.json +++ b/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" ], diff --git a/open-api/typescript-sdk/src/fetch-client.ts b/open-api/typescript-sdk/src/fetch-client.ts index d42725a235..2e5c5779b2 100644 --- a/open-api/typescript-sdk/src/fetch-client.ts +++ b/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; diff --git a/server/src/controllers/asset-media.controller.ts b/server/src/controllers/asset-media.controller.ts index 553f1a261f..fd405b8928 100644 --- a/server/src/controllers/asset-media.controller.ts +++ b/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, diff --git a/server/src/controllers/asset.controller.ts b/server/src/controllers/asset.controller.ts index 8a5b5fb0b6..9a7252a087 100644 --- a/server/src/controllers/asset.controller.ts +++ b/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);