feat: api key dto docs

packages/server/src/modules/Auth/AuthApiKeys.controllers.ts

@@ -1,12 +1,30 @@
 import { Controller, Post, Param, Get, Put } from '@nestjs/common';
 import { GenerateApiKey } from './commands/GenerateApiKey.service';
 import { GetApiKeysService } from './queries/GetApiKeys.service';
-import { ApiExcludeController, ApiTags } from '@nestjs/swagger';
+import {
+  ApiTags,
+  ApiOperation,
+  ApiResponse,
+  ApiParam,
+  ApiExtraModels,
+  getSchemaPath,
+} from '@nestjs/swagger';
 import { ApiCommonHeaders } from '@/common/decorators/ApiCommonHeaders';
+import {
+  ApiKeyResponseDto,
+  ApiKeyRevokeResponseDto,
+  ApiKeyListResponseDto,
+  ApiKeyListItemDto,
+} from './dtos/ApiKey.dto';
 
 @Controller('api-keys')
 @ApiTags('Api keys')
 @ApiCommonHeaders()
+@ApiExtraModels(
+  ApiKeyResponseDto,
+  ApiKeyRevokeResponseDto,
+  ApiKeyListResponseDto,
+)
 export class AuthApiKeysController {
   constructor(
     private readonly getApiKeysService: GetApiKeysService,
@@ -14,17 +32,42 @@ export class AuthApiKeysController {
   ) {}
 
   @Post('generate')
+  @ApiOperation({ summary: 'Generate a new API key' })
+  @ApiResponse({
+    status: 201,
+    description: 'The generated API key',
+    type: ApiKeyResponseDto,
+  })
   async generate() {
     return this.generateApiKeyService.generate();
   }
 
   @Put(':id/revoke')
+  @ApiOperation({ summary: 'Revoke an API key' })
+  @ApiParam({ name: 'id', type: Number, description: 'API key ID' })
+  @ApiResponse({
+    status: 200,
+    description: 'API key revoked',
+    type: ApiKeyRevokeResponseDto,
+  })
   async revoke(@Param('id') id: number) {
     return this.generateApiKeyService.revoke(id);
   }
 
   @Get()
+  @ApiOperation({ summary: 'Get all API keys for the current tenant' })
+  @ApiResponse({
+    status: 200,
+    description: 'List of API keys',
+    schema: {
+      type: 'array',
+      items: {
+        $ref: getSchemaPath(ApiKeyListItemDto),
+      },
+    },
+  })
   async getApiKeys() {
-    return this.getApiKeysService.getApiKeys();
+    const data = await this.getApiKeysService.getApiKeys();
+    return data;
   }
 }

packages/server/src/modules/Auth/dtos/ApiKey.dto.ts

@@ -0,0 +1,52 @@
+import { ApiProperty } from '@nestjs/swagger';
+
+export class ApiKeyResponseDto {
+  @ApiProperty({ example: 1, description: 'API key ID' })
+  id: number;
+
+  @ApiProperty({
+    example: 'bc_1234567890abcdef',
+    description: 'The API key string',
+  })
+  key: string;
+}
+
+export class ApiKeyRevokeResponseDto {
+  @ApiProperty({ example: 1, description: 'API key ID' })
+  id: number;
+
+  @ApiProperty({
+    example: true,
+    description: 'Whether the API key was revoked',
+  })
+  revoked: boolean;
+}
+
+export class ApiKeyListItemDto {
+  @ApiProperty({ example: 1, description: 'API key ID' })
+  id: number;
+
+  @ApiProperty({ example: 'My API Key', description: 'API key name' })
+  name?: string;
+
+  @ApiProperty({
+    example: '2024-01-01T00:00:00.000Z',
+    description: 'Creation date',
+  })
+  createdAt: Date;
+
+  @ApiProperty({
+    example: '2024-12-31T23:59:59.000Z',
+    required: false,
+    description: 'Expiration date',
+  })
+  expiresAt?: Date;
+
+  @ApiProperty({ example: false, description: 'Whether the key is revoked' })
+  revoked: boolean;
+}
+
+export class ApiKeyListResponseDto {
+  @ApiProperty({ type: [ApiKeyListItemDto] })
+  data: ApiKeyListItemDto[];
+}