docs(openapi): preview for #25185

[timonrieger]

@jrasm91 as discussed on Discord and #25185 . Here is the proposal:

• only update dtos
• don't use jsdoc as this has no openapi capabilities, instead use the built-in ApiProperty from @nestjs/swagger
• don't add descriptions to endpoints/controllers (yet 😄 )

If you accept this, I will go update #25185 (or recreate it) with this proposal

[immich-push-o-matic]

Label error. Requires exactly 1 of: changelog:.*. Found: 🗄️server. A maintainer will add the required label.

[jrasm91]

Yes, that all looks great. Although, can you use @Property instead of @ApiProperty? It's our custom one which supports adding history via new HistoryBuilder().added('v2.5.0').beta('v2.5.0'). If you are going to update a lot of properties, you probably can go ahead and add added('v2').stable('v2') at the same time.

[timonrieger]

Although, can you use @Property instead of @ApiProperty? It's our custom one which supports adding history via new HistoryBuilder().added('v2.5.0').beta('v2.5.0').

I just searched through the codebase and saw that the HistoryBuilder() is being applied to exclusively Endpoint decorators. I don't understand the link to the (Api)Property here. Could you clarify?

immich/server/src/controllers/user.controller.ts

Lines 183 to 187 in ec889c0

	@Endpoint({
	summary: 'Create user profile image',
	description: 'Upload and set a new profile image for the current user.',
	history: new HistoryBuilder().added('v1').beta('v1').stable('v2'),
	})

[jrasm91]

https://github.com/immich-app/immich/blob/main/server%2Fsrc%2Fdtos%2Fperson.dto.ts#L117

[timonrieger]

closing this at it just served as the proposal