feat: endpoint versioning (#23858)

server/src/controllers/auth.controller.ts

@@ -1,6 +1,7 @@
 import { Body, Controller, Delete, Get, HttpCode, HttpStatus, Post, Put, Req, Res } from '@nestjs/common';
-import { ApiOperation, ApiTags } from '@nestjs/swagger';
+import { ApiTags } from '@nestjs/swagger';
 import { Request, Response } from 'express';
+import { Endpoint, HistoryBuilder } from 'src/decorators';
 import {
   AuthDto,
   AuthStatusResponseDto,
@@ -27,9 +28,10 @@ export class AuthController {
   constructor(private service: AuthService) {}
 
   @Post('login')
-  @ApiOperation({
+  @Endpoint({
     summary: 'Login',
     description: 'Login with username and password and receive a session token.',
+    history: new HistoryBuilder().added('v1').beta('v1').stable('v2'),
   })
   async login(
     @Res({ passthrough: true }) res: Response,
@@ -48,18 +50,20 @@ export class AuthController {
   }
 
   @Post('admin-sign-up')
-  @ApiOperation({
+  @Endpoint({
     summary: 'Register admin',
     description: 'Create the first admin user in the system.',
+    history: new HistoryBuilder().added('v1').beta('v1').stable('v2'),
   })
   signUpAdmin(@Body() dto: SignUpDto): Promise<UserAdminResponseDto> {
     return this.service.adminSignUp(dto);
   }
 
   @Post('validateToken')
-  @ApiOperation({
+  @Endpoint({
     summary: 'Validate access token',
     description: 'Validate the current authorization method is still valid.',
+    history: new HistoryBuilder().added('v1').beta('v1').stable('v2'),
   })
   @Authenticated({ permission: false })
   @HttpCode(HttpStatus.OK)
@@ -70,9 +74,10 @@ export class AuthController {
   @Post('change-password')
   @Authenticated({ permission: Permission.AuthChangePassword })
   @HttpCode(HttpStatus.OK)
-  @ApiOperation({
+  @Endpoint({
     summary: 'Change password',
     description: 'Change the password of the current user.',
+    history: new HistoryBuilder().added('v1').beta('v1').stable('v2'),
   })
   changePassword(@Auth() auth: AuthDto, @Body() dto: ChangePasswordDto): Promise<UserAdminResponseDto> {
     return this.service.changePassword(auth, dto);
@@ -81,9 +86,10 @@ export class AuthController {
   @Post('logout')
   @Authenticated()
   @HttpCode(HttpStatus.OK)
-  @ApiOperation({
+  @Endpoint({
     summary: 'Logout',
     description: 'Logout the current user and invalidate the session token.',
+    history: new HistoryBuilder().added('v1').beta('v1').stable('v2'),
   })
   async logout(
     @Req() request: Request,
@@ -102,7 +108,7 @@ export class AuthController {
 
   @Get('status')
   @Authenticated()
-  @ApiOperation({
+  @Endpoint({
     summary: 'Retrieve auth status',
     description:
       'Get information about the current session, including whether the user has a password, and if the session can access locked assets.',
@@ -114,9 +120,10 @@ export class AuthController {
   @Post('pin-code')
   @Authenticated({ permission: Permission.PinCodeCreate })
   @HttpCode(HttpStatus.NO_CONTENT)
-  @ApiOperation({
+  @Endpoint({
     summary: 'Setup pin code',
     description: 'Setup a new pin code for the current user.',
+    history: new HistoryBuilder().added('v1').beta('v1').stable('v2'),
   })
   setupPinCode(@Auth() auth: AuthDto, @Body() dto: PinCodeSetupDto): Promise<void> {
     return this.service.setupPinCode(auth, dto);
@@ -125,9 +132,10 @@ export class AuthController {
   @Put('pin-code')
   @Authenticated({ permission: Permission.PinCodeUpdate })
   @HttpCode(HttpStatus.NO_CONTENT)
-  @ApiOperation({
+  @Endpoint({
     summary: 'Change pin code',
     description: 'Change the pin code for the current user.',
+    history: new HistoryBuilder().added('v1').beta('v1').stable('v2'),
   })
   async changePinCode(@Auth() auth: AuthDto, @Body() dto: PinCodeChangeDto): Promise<void> {
     return this.service.changePinCode(auth, dto);
@@ -136,9 +144,10 @@ export class AuthController {
   @Delete('pin-code')
   @Authenticated({ permission: Permission.PinCodeDelete })
   @HttpCode(HttpStatus.NO_CONTENT)
-  @ApiOperation({
+  @Endpoint({
     summary: 'Reset pin code',
     description: 'Reset the pin code for the current user by providing the account password',
+    history: new HistoryBuilder().added('v1').beta('v1').stable('v2'),
   })
   async resetPinCode(@Auth() auth: AuthDto, @Body() dto: PinCodeResetDto): Promise<void> {
     return this.service.resetPinCode(auth, dto);
@@ -147,9 +156,10 @@ export class AuthController {
   @Post('session/unlock')
   @Authenticated()
   @HttpCode(HttpStatus.NO_CONTENT)
-  @ApiOperation({
+  @Endpoint({
     summary: 'Unlock auth session',
     description: 'Temporarily grant the session elevated access to locked assets by providing the correct PIN code.',
+    history: new HistoryBuilder().added('v1').beta('v1').stable('v2'),
   })
   async unlockAuthSession(@Auth() auth: AuthDto, @Body() dto: SessionUnlockDto): Promise<void> {
     return this.service.unlockSession(auth, dto);
@@ -157,9 +167,10 @@ export class AuthController {
 
   @Post('session/lock')
   @Authenticated()
-  @ApiOperation({
+  @Endpoint({
     summary: 'Lock auth session',
     description: 'Remove elevated access to locked assets from the current session.',
+    history: new HistoryBuilder().added('v1').beta('v1').stable('v2'),
   })
   @HttpCode(HttpStatus.NO_CONTENT)
   async lockAuthSession(@Auth() auth: AuthDto): Promise<void> {