feat: endpoint versioning (#23858)

server/src/controllers/user.controller.ts

@@ -13,8 +13,9 @@ import {
   UploadedFile,
   UseInterceptors,
 } from '@nestjs/common';
-import { ApiBody, ApiConsumes, ApiOperation, ApiTags } from '@nestjs/swagger';
+import { ApiBody, ApiConsumes, ApiTags } from '@nestjs/swagger';
 import { NextFunction, Response } from 'express';
+import { Endpoint, HistoryBuilder } from 'src/decorators';
 import { AuthDto } from 'src/dtos/auth.dto';
 import { LicenseKeyDto, LicenseResponseDto } from 'src/dtos/license.dto';
 import { OnboardingDto, OnboardingResponseDto } from 'src/dtos/onboarding.dto';
@@ -39,16 +40,21 @@ export class UserController {
 
   @Get()
   @Authenticated({ permission: Permission.UserRead })
-  @ApiOperation({ summary: 'Get all users', description: 'Retrieve a list of all users on the server.' })
+  @Endpoint({
+    summary: 'Get all users',
+    description: 'Retrieve a list of all users on the server.',
+    history: new HistoryBuilder().added('v1').beta('v1').stable('v2'),
+  })
   searchUsers(@Auth() auth: AuthDto): Promise<UserResponseDto[]> {
     return this.service.search(auth);
   }
 
   @Get('me')
   @Authenticated({ permission: Permission.UserRead })
-  @ApiOperation({
+  @Endpoint({
     summary: 'Get current user',
     description: 'Retrieve information about the user making the API request.',
+    history: new HistoryBuilder().added('v1').beta('v1').stable('v2'),
   })
   getMyUser(@Auth() auth: AuthDto): Promise<UserAdminResponseDto> {
     return this.service.getMe(auth);
@@ -56,21 +62,33 @@ export class UserController {
 
   @Put('me')
   @Authenticated({ permission: Permission.UserUpdate })
-  @ApiOperation({ summary: 'Update current user', description: 'Update the current user making teh API request.' })
+  @Endpoint({
+    summary: 'Update current user',
+    description: 'Update the current user making teh API request.',
+    history: new HistoryBuilder().added('v1').beta('v1').stable('v2'),
+  })
   updateMyUser(@Auth() auth: AuthDto, @Body() dto: UserUpdateMeDto): Promise<UserAdminResponseDto> {
     return this.service.updateMe(auth, dto);
   }
 
   @Get('me/preferences')
   @Authenticated({ permission: Permission.UserPreferenceRead })
-  @ApiOperation({ summary: 'Get my preferences', description: 'Retrieve the preferences for the current user.' })
+  @Endpoint({
+    summary: 'Get my preferences',
+    description: 'Retrieve the preferences for the current user.',
+    history: new HistoryBuilder().added('v1').beta('v1').stable('v2'),
+  })
   getMyPreferences(@Auth() auth: AuthDto): Promise<UserPreferencesResponseDto> {
     return this.service.getMyPreferences(auth);
   }
 
   @Put('me/preferences')
   @Authenticated({ permission: Permission.UserPreferenceUpdate })
-  @ApiOperation({ summary: 'Update my preferences', description: 'Update the preferences of the current user.' })
+  @Endpoint({
+    summary: 'Update my preferences',
+    description: 'Update the preferences of the current user.',
+    history: new HistoryBuilder().added('v1').beta('v1').stable('v2'),
+  })
   updateMyPreferences(
     @Auth() auth: AuthDto,
     @Body() dto: UserPreferencesUpdateDto,
@@ -80,9 +98,10 @@ export class UserController {
 
   @Get('me/license')
   @Authenticated({ permission: Permission.UserLicenseRead })
-  @ApiOperation({
+  @Endpoint({
     summary: 'Retrieve user product key',
     description: 'Retrieve information about whether the current user has a registered product key.',
+    history: new HistoryBuilder().added('v1').beta('v1').stable('v2'),
   })
   getUserLicense(@Auth() auth: AuthDto): Promise<LicenseResponseDto> {
     return this.service.getLicense(auth);
@@ -90,9 +109,10 @@ export class UserController {
 
   @Put('me/license')
   @Authenticated({ permission: Permission.UserLicenseUpdate })
-  @ApiOperation({
+  @Endpoint({
     summary: 'Set user product key',
     description: 'Register a product key for the current user.',
+    history: new HistoryBuilder().added('v1').beta('v1').stable('v2'),
   })
   async setUserLicense(@Auth() auth: AuthDto, @Body() license: LicenseKeyDto): Promise<LicenseResponseDto> {
     return this.service.setLicense(auth, license);
@@ -101,9 +121,10 @@ export class UserController {
   @Delete('me/license')
   @Authenticated({ permission: Permission.UserLicenseDelete })
   @HttpCode(HttpStatus.NO_CONTENT)
-  @ApiOperation({
+  @Endpoint({
     summary: 'Delete user product key',
     description: 'Delete the registered product key for the current user.',
+    history: new HistoryBuilder().added('v1').beta('v1').stable('v2'),
   })
   async deleteUserLicense(@Auth() auth: AuthDto): Promise<void> {
     await this.service.deleteLicense(auth);
@@ -111,9 +132,10 @@ export class UserController {
 
   @Get('me/onboarding')
   @Authenticated({ permission: Permission.UserOnboardingRead })
-  @ApiOperation({
+  @Endpoint({
     summary: 'Retrieve user onboarding',
     description: 'Retrieve the onboarding status of the current user.',
+    history: new HistoryBuilder().added('v1').beta('v1').stable('v2'),
   })
   getUserOnboarding(@Auth() auth: AuthDto): Promise<OnboardingResponseDto> {
     return this.service.getOnboarding(auth);
@@ -121,9 +143,10 @@ export class UserController {
 
   @Put('me/onboarding')
   @Authenticated({ permission: Permission.UserOnboardingUpdate })
-  @ApiOperation({
+  @Endpoint({
     summary: 'Update user onboarding',
     description: 'Update the onboarding status of the current user.',
+    history: new HistoryBuilder().added('v1').beta('v1').stable('v2'),
   })
   async setUserOnboarding(@Auth() auth: AuthDto, @Body() Onboarding: OnboardingDto): Promise<OnboardingResponseDto> {
     return this.service.setOnboarding(auth, Onboarding);
@@ -132,9 +155,10 @@ export class UserController {
   @Delete('me/onboarding')
   @Authenticated({ permission: Permission.UserOnboardingDelete })
   @HttpCode(HttpStatus.NO_CONTENT)
-  @ApiOperation({
+  @Endpoint({
     summary: 'Delete user onboarding',
     description: 'Delete the onboarding status of the current user.',
+    history: new HistoryBuilder().added('v1').beta('v1').stable('v2'),
   })
   async deleteUserOnboarding(@Auth() auth: AuthDto): Promise<void> {
     await this.service.deleteOnboarding(auth);
@@ -142,9 +166,10 @@ export class UserController {
 
   @Get(':id')
   @Authenticated({ permission: Permission.UserRead })
-  @ApiOperation({
+  @Endpoint({
     summary: 'Retrieve a user',
     description: 'Retrieve a specific user by their ID.',
+    history: new HistoryBuilder().added('v1').beta('v1').stable('v2'),
   })
   getUser(@Param() { id }: UUIDParamDto): Promise<UserResponseDto> {
     return this.service.get(id);
@@ -155,9 +180,10 @@ export class UserController {
   @UseInterceptors(FileUploadInterceptor)
   @ApiConsumes('multipart/form-data')
   @ApiBody({ description: 'A new avatar for the user', type: CreateProfileImageDto })
-  @ApiOperation({
+  @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'),
   })
   createProfileImage(
     @Auth() auth: AuthDto,
@@ -169,9 +195,10 @@ export class UserController {
   @Delete('profile-image')
   @Authenticated({ permission: Permission.UserProfileImageDelete })
   @HttpCode(HttpStatus.NO_CONTENT)
-  @ApiOperation({
+  @Endpoint({
     summary: 'Delete user profile image',
     description: 'Delete the profile image of the current user.',
+    history: new HistoryBuilder().added('v1').beta('v1').stable('v2'),
   })
   deleteProfileImage(@Auth() auth: AuthDto): Promise<void> {
     return this.service.deleteProfileImage(auth);
@@ -180,9 +207,10 @@ export class UserController {
   @Get(':id/profile-image')
   @FileResponse()
   @Authenticated({ permission: Permission.UserProfileImageRead })
-  @ApiOperation({
+  @Endpoint({
     summary: 'Retrieve user profile image',
     description: 'Retrieve the profile image file for a user.',
+    history: new HistoryBuilder().added('v1').beta('v1').stable('v2'),
   })
   async getProfileImage(@Res() res: Response, @Next() next: NextFunction, @Param() { id }: UUIDParamDto) {
     await sendFile(res, next, () => this.service.getProfileImage(id), this.logger);