feat: endpoint versioning (#23858)

server/src/controllers/album.controller.ts

@@ -1,5 +1,6 @@
 import { Body, Controller, Delete, Get, HttpCode, HttpStatus, Param, Patch, Post, Put, Query } from '@nestjs/common';
-import { ApiOperation, ApiTags } from '@nestjs/swagger';
+import { ApiTags } from '@nestjs/swagger';
+import { Endpoint, HistoryBuilder } from 'src/decorators';
 import {
   AddUsersDto,
   AlbumInfoDto,
@@ -26,9 +27,10 @@ export class AlbumController {
 
   @Get()
   @Authenticated({ permission: Permission.AlbumRead })
-  @ApiOperation({
+  @Endpoint({
     summary: 'List all albums',
     description: 'Retrieve a list of albums available to the authenticated user.',
+    history: new HistoryBuilder().added('v1').beta('v1').stable('v2'),
   })
   getAllAlbums(@Auth() auth: AuthDto, @Query() query: GetAlbumsDto): Promise<AlbumResponseDto[]> {
     return this.service.getAll(auth, query);
@@ -36,9 +38,10 @@ export class AlbumController {
 
   @Post()
   @Authenticated({ permission: Permission.AlbumCreate })
-  @ApiOperation({
+  @Endpoint({
     summary: 'Create an album',
     description: 'Create a new album. The album can also be created with initial users and assets.',
+    history: new HistoryBuilder().added('v1').beta('v1').stable('v2'),
   })
   createAlbum(@Auth() auth: AuthDto, @Body() dto: CreateAlbumDto): Promise<AlbumResponseDto> {
     return this.service.create(auth, dto);
@@ -46,9 +49,10 @@ export class AlbumController {
 
   @Get('statistics')
   @Authenticated({ permission: Permission.AlbumStatistics })
-  @ApiOperation({
+  @Endpoint({
     summary: 'Retrieve album statistics',
     description: 'Returns statistics about the albums available to the authenticated user.',
+    history: new HistoryBuilder().added('v1').beta('v1').stable('v2'),
   })
   getAlbumStatistics(@Auth() auth: AuthDto): Promise<AlbumStatisticsResponseDto> {
     return this.service.getStatistics(auth);
@@ -56,9 +60,10 @@ export class AlbumController {
 
   @Authenticated({ permission: Permission.AlbumRead, sharedLink: true })
   @Get(':id')
-  @ApiOperation({
+  @Endpoint({
     summary: 'Retrieve an album',
     description: 'Retrieve information about a specific album by its ID.',
+    history: new HistoryBuilder().added('v1').beta('v1').stable('v2'),
   })
   getAlbumInfo(
     @Auth() auth: AuthDto,
@@ -70,10 +75,11 @@ export class AlbumController {
 
   @Patch(':id')
   @Authenticated({ permission: Permission.AlbumUpdate })
-  @ApiOperation({
+  @Endpoint({
     summary: 'Update an album',
     description:
       'Update the information of a specific album by its ID. This endpoint can be used to update the album name, description, sort order, etc. However, it is not used to add or remove assets or users from the album.',
+    history: new HistoryBuilder().added('v1').beta('v1').stable('v2'),
   })
   updateAlbumInfo(
     @Auth() auth: AuthDto,
@@ -86,10 +92,11 @@ export class AlbumController {
   @Delete(':id')
   @Authenticated({ permission: Permission.AlbumDelete })
   @HttpCode(HttpStatus.NO_CONTENT)
-  @ApiOperation({
+  @Endpoint({
     summary: 'Delete an album',
     description:
       'Delete a specific album by its ID. Note the album is initially trashed and then immediately scheduled for deletion, but relies on a background job to complete the process.',
+    history: new HistoryBuilder().added('v1').beta('v1').stable('v2'),
   })
   deleteAlbum(@Auth() auth: AuthDto, @Param() { id }: UUIDParamDto) {
     return this.service.delete(auth, id);
@@ -97,9 +104,10 @@ export class AlbumController {
 
   @Put(':id/assets')
   @Authenticated({ permission: Permission.AlbumAssetCreate, sharedLink: true })
-  @ApiOperation({
+  @Endpoint({
     summary: 'Add assets to an album',
     description: 'Add multiple assets to a specific album by its ID.',
+    history: new HistoryBuilder().added('v1').beta('v1').stable('v2'),
   })
   addAssetsToAlbum(
     @Auth() auth: AuthDto,
@@ -111,9 +119,10 @@ export class AlbumController {
 
   @Put('assets')
   @Authenticated({ permission: Permission.AlbumAssetCreate, sharedLink: true })
-  @ApiOperation({
+  @Endpoint({
     summary: 'Add assets to albums',
     description: 'Send a list of asset IDs and album IDs to add each asset to each album.',
+    history: new HistoryBuilder().added('v1').beta('v1').stable('v2'),
   })
   addAssetsToAlbums(@Auth() auth: AuthDto, @Body() dto: AlbumsAddAssetsDto): Promise<AlbumsAddAssetsResponseDto> {
     return this.service.addAssetsToAlbums(auth, dto);
@@ -121,9 +130,10 @@ export class AlbumController {
 
   @Delete(':id/assets')
   @Authenticated({ permission: Permission.AlbumAssetDelete })
-  @ApiOperation({
+  @Endpoint({
     summary: 'Remove assets from an album',
     description: 'Remove multiple assets from a specific album by its ID.',
+    history: new HistoryBuilder().added('v1').beta('v1').stable('v2'),
   })
   removeAssetFromAlbum(
     @Auth() auth: AuthDto,
@@ -135,9 +145,10 @@ export class AlbumController {
 
   @Put(':id/users')
   @Authenticated({ permission: Permission.AlbumUserCreate })
-  @ApiOperation({
+  @Endpoint({
     summary: 'Share album with users',
     description: 'Share an album with multiple users. Each user can be given a specific role in the album.',
+    history: new HistoryBuilder().added('v1').beta('v1').stable('v2'),
   })
   addUsersToAlbum(
     @Auth() auth: AuthDto,
@@ -150,9 +161,10 @@ export class AlbumController {
   @Put(':id/user/:userId')
   @Authenticated({ permission: Permission.AlbumUserUpdate })
   @HttpCode(HttpStatus.NO_CONTENT)
-  @ApiOperation({
+  @Endpoint({
     summary: 'Update user role',
     description: 'Change the role for a specific user in a specific album.',
+    history: new HistoryBuilder().added('v1').beta('v1').stable('v2'),
   })
   updateAlbumUser(
     @Auth() auth: AuthDto,
@@ -166,9 +178,10 @@ export class AlbumController {
   @Delete(':id/user/:userId')
   @Authenticated({ permission: Permission.AlbumUserDelete })
   @HttpCode(HttpStatus.NO_CONTENT)
-  @ApiOperation({
+  @Endpoint({
     summary: 'Remove user from album',
     description: 'Remove a user from an album. Use an ID of "me" to leave a shared album.',
+    history: new HistoryBuilder().added('v1').beta('v1').stable('v2'),
   })
   removeUserFromAlbum(
     @Auth() auth: AuthDto,