github-mirrors/immich
1
0
Fork 0
mirror of https://github.com/immich-app/immich.git synced 2026-03-08 02:57:48 +03:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
* 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>
This commit is contained in:
Timon
2026-01-29 14:49:15 +01:00
committed by GitHub
parent eadb2f89af
commit 8db61d341f
377 changed files with 5554 additions and 735 deletions
Download Patch File Download Diff File Expand all files Collapse all files

54
server/src/dtos/asset-response.dto.ts
View File

@@ -1,4 +1,4 @@
import { ApiProperty } from '@nestjs/swagger';
import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
import { Selectable } from 'kysely';
import { AssetFace, AssetFile, Exif, Stack, Tag, User } from 'src/database';
import { HistoryBuilder, Property } from 'src/decorators';
@@ -18,13 +18,16 @@ import { ImageDimensions } from 'src/types';
import { getDimensions } from 'src/utils/asset.util';
import { hexOrBufferToBase64 } from 'src/utils/bytes';
import { mimeTypes } from 'src/utils/mime-types';
import { ValidateEnum } from 'src/validation';
import { ValidateEnum, ValidateUUID } from 'src/validation';
export class SanitizedAssetResponseDto {
@ApiProperty({ description: 'Asset ID' })
id!: string;
@ValidateEnum({ enum: AssetType, name: 'AssetTypeEnum' })
@ValidateEnum({ enum: AssetType, name: 'AssetTypeEnum', description: 'Asset type' })
type!: AssetType;
@ApiProperty({ description: 'Thumbhash for thumbnail generation' })
thumbhash!: string | null;
@ApiPropertyOptional({ description: 'Original MIME type' })
originalMimeType?: string;
@ApiProperty({
type: 'string',
@@ -34,10 +37,15 @@ export class SanitizedAssetResponseDto {
example: '2024-01-15T14:30:00.000Z',
})
localDateTime!: Date;
@ApiProperty({ description: 'Video duration (for videos)' })
duration!: string;
@ApiPropertyOptional({ description: 'Live photo video ID' })
livePhotoVideoId?: string | null;
@ApiProperty({ description: 'Whether asset has metadata' })
hasMetadata!: boolean;
@ApiProperty({ description: 'Asset width' })
width!: number | null;
@ApiProperty({ description: 'Asset height' })
height!: number | null;
}
@@ -49,13 +57,24 @@ export class AssetResponseDto extends SanitizedAssetResponseDto {
example: '2024-01-15T20:30:00.000Z',
})
createdAt!: Date;
@ApiProperty({ description: 'Device asset ID' })
deviceAssetId!: string;
@ApiProperty({ description: 'Device ID' })
deviceId!: string;
@ApiProperty({ description: 'Owner user ID' })
ownerId!: string;
// Description lives on schema to avoid duplication
@ApiPropertyOptional({ description: undefined })
owner?: UserResponseDto;
@Property({ history: new HistoryBuilder().added('v1').deprecated('v1') })
@ValidateUUID({
nullable: true,
description: 'Library ID',
history: new HistoryBuilder().added('v1').deprecated('v1'),
})
libraryId?: string | null;
@ApiProperty({ description: 'Original file path' })
originalPath!: string;
@ApiProperty({ description: 'Original file name' })
originalFileName!: string;
@ApiProperty({
type: 'string',
@@ -81,24 +100,39 @@ export class AssetResponseDto extends SanitizedAssetResponseDto {
example: '2024-01-16T12:45:30.000Z',
})
updatedAt!: Date;
@ApiProperty({ description: 'Is favorite' })
isFavorite!: boolean;
@ApiProperty({ description: 'Is archived' })
isArchived!: boolean;
@ApiProperty({ description: 'Is trashed' })
isTrashed!: boolean;
@ApiProperty({ description: 'Is offline' })
isOffline!: boolean;
@ValidateEnum({ enum: AssetVisibility, name: 'AssetVisibility' })
@ValidateEnum({ enum: AssetVisibility, name: 'AssetVisibility', description: 'Asset visibility' })
visibility!: AssetVisibility;
// Description lives on schema to avoid duplication
@ApiPropertyOptional({ description: undefined })
exifInfo?: ExifResponseDto;
// Description lives on schema to avoid duplication
@ApiPropertyOptional({ description: undefined })
tags?: TagResponseDto[];
// Description lives on schema to avoid duplication
@ApiPropertyOptional({ description: undefined })
people?: PersonWithFacesResponseDto[];
// Description lives on schema to avoid duplication
@ApiPropertyOptional({ description: undefined })
unassignedFaces?: AssetFaceWithoutPersonResponseDto[];
/**base64 encoded sha1 hash */
@ApiProperty({ description: 'Base64 encoded SHA1 hash' })
checksum!: string;
// Description lives on schema to avoid duplication
@ApiPropertyOptional({ description: undefined })
stack?: AssetStackResponseDto | null;
@ApiPropertyOptional({ description: 'Duplicate group ID' })
duplicateId?: string | null;
@Property({ history: new HistoryBuilder().added('v1').deprecated('v1.113.0') })
@Property({ description: 'Is resized', history: new HistoryBuilder().added('v1').deprecated('v1.113.0') })
resized?: boolean;
@Property({ history: new HistoryBuilder().added('v2.5.0').beta('v2.5.0') })
@Property({ description: 'Is edited', history: new HistoryBuilder().added('v2.5.0').beta('v2.5.0') })
isEdited!: boolean;
}
@@ -143,11 +177,13 @@ export type MapAsset = {
};
export class AssetStackResponseDto {
@ApiProperty({ description: 'Stack ID' })
id!: string;
@ApiProperty({ description: 'Primary asset ID' })
primaryAssetId!: string;
@ApiProperty({ type: 'integer' })
@ApiProperty({ type: 'integer', description: 'Number of assets in stack' })
assetCount!: number;
}