feat: endpoint versioning (#23858)

server/src/controllers/partner.controller.ts

@@ -1,6 +1,6 @@
 import { Body, Controller, Delete, Get, HttpCode, HttpStatus, Param, Post, Put, Query } from '@nestjs/common';
-import { ApiOperation, ApiTags } from '@nestjs/swagger';
-import { EndpointLifecycle } from 'src/decorators';
+import { ApiTags } from '@nestjs/swagger';
+import { Endpoint, HistoryBuilder } from 'src/decorators';
 import { AuthDto } from 'src/dtos/auth.dto';
 import { PartnerCreateDto, PartnerResponseDto, PartnerSearchDto, PartnerUpdateDto } from 'src/dtos/partner.dto';
 import { ApiTag, Permission } from 'src/enum';
@@ -15,9 +15,10 @@ export class PartnerController {
 
   @Get()
   @Authenticated({ permission: Permission.PartnerRead })
-  @ApiOperation({
+  @Endpoint({
     summary: 'Retrieve partners',
     description: 'Retrieve a list of partners with whom assets are shared.',
+    history: new HistoryBuilder().added('v1').beta('v1').stable('v2'),
   })
   getPartners(@Auth() auth: AuthDto, @Query() dto: PartnerSearchDto): Promise<PartnerResponseDto[]> {
     return this.service.search(auth, dto);
@@ -25,19 +26,20 @@ export class PartnerController {
 
   @Post()
   @Authenticated({ permission: Permission.PartnerCreate })
-  @ApiOperation({
+  @Endpoint({
     summary: 'Create a partner',
     description: 'Create a new partner to share assets with.',
+    history: new HistoryBuilder().added('v1').beta('v1').stable('v2'),
   })
   createPartner(@Auth() auth: AuthDto, @Body() dto: PartnerCreateDto): Promise<PartnerResponseDto> {
     return this.service.create(auth, dto);
   }
 
   @Post(':id')
-  @EndpointLifecycle({
-    deprecatedAt: 'v1.141.0',
+  @Endpoint({
     summary: 'Create a partner',
     description: 'Create a new partner to share assets with.',
+    history: new HistoryBuilder().added('v1').deprecated('v1', { replacementId: 'createPartner' }),
   })
   @Authenticated({ permission: Permission.PartnerCreate })
   createPartnerDeprecated(@Auth() auth: AuthDto, @Param() { id }: UUIDParamDto): Promise<PartnerResponseDto> {
@@ -46,9 +48,10 @@ export class PartnerController {
 
   @Put(':id')
   @Authenticated({ permission: Permission.PartnerUpdate })
-  @ApiOperation({
+  @Endpoint({
     summary: 'Update a partner',
     description: "Specify whether a partner's assets should appear in the user's timeline.",
+    history: new HistoryBuilder().added('v1').beta('v1').stable('v2'),
   })
   updatePartner(
     @Auth() auth: AuthDto,
@@ -61,9 +64,10 @@ export class PartnerController {
   @Delete(':id')
   @Authenticated({ permission: Permission.PartnerDelete })
   @HttpCode(HttpStatus.NO_CONTENT)
-  @ApiOperation({
+  @Endpoint({
     summary: 'Remove a partner',
     description: 'Stop sharing assets with a partner.',
+    history: new HistoryBuilder().added('v1').beta('v1').stable('v2'),
   })
   removePartner(@Auth() auth: AuthDto, @Param() { id }: UUIDParamDto): Promise<void> {
     return this.service.remove(auth, id);