docs(api): Add swagger docs of API key controller

apps/api/src/api-key/api-key.e2e.spec.ts

@@ -261,7 +261,7 @@ describe('Api Key Role Controller Tests', () => {
  }
  })
 
- expect(response.statusCode).toBe(200)
+ expect(response.statusCode).toBe(204)
  })
 
  afterAll(async () => {

apps/api/src/api-key/controller/api-key.controller.ts

@@ -3,6 +3,7 @@ import {
  Controller,
  Delete,
  Get,
+ HttpCode,
  Param,
  Post,
  Put,
@@ -14,19 +15,81 @@ import { CreateApiKey } from '../dto/create.api-key/create.api-key'
 import { UpdateApiKey } from '../dto/update.api-key/update.api-key'
 import { Authority, User } from '@prisma/client'
 import { RequiredApiKeyAuthorities } from '../../decorators/required-api-key-authorities.decorator'
+import {
+ ApiBearerAuth,
+ ApiCreatedResponse,
+ ApiForbiddenResponse,
+ ApiNoContentResponse,
+ ApiOkResponse,
+ ApiOperation,
+ ApiParam,
+ ApiQuery,
+ ApiSecurity,
+ ApiTags
+} from '@nestjs/swagger'
+import { invalidAuthenticationResponse } from '../../common/static'
+
+const baseProperties = {
+ id: { type: 'string' },
+ name: { type: 'string' },
+ expiresAt: { type: 'string' },
+ authorities: { type: 'array', items: { type: 'string' } },
+ createdAt: { type: 'string' },
+ updatedAt: { type: 'string' }
+}
+
+const apiKeySchemaWithValue = {
+ type: 'object',
+ properties: {
+ ...baseProperties,
+ value: { type: 'string' }
+ }
+}
+
+const apiKeySchema = {
+ type: 'object',
+ properties: baseProperties
+}
 
 @Controller('api-key')
+@ApiBearerAuth()
+@ApiSecurity('api_key')
+@ApiTags('API Key Controller')
 export class ApiKeyController {
  constructor(private readonly apiKeyService: ApiKeyService) {}
 
  @Post()
  @RequiredApiKeyAuthorities(Authority.CREATE_API_KEY)
+ @ApiOperation({
+ summary: 'Create API key',
+ description: 'This endpoint creates a new API key'
+ })
+ @ApiCreatedResponse({
+ schema: apiKeySchemaWithValue,
+ description: 'API key created successfully'
+ })
+ @ApiForbiddenResponse(invalidAuthenticationResponse)
  async createApiKey(@CurrentUser() user: User, @Body() dto: CreateApiKey) {
  return this.apiKeyService.createApiKey(user, dto)
  }
 
  @Put(':id')
  @RequiredApiKeyAuthorities(Authority.UPDATE_API_KEY)
+ @ApiOperation({
+ summary: 'Update API key',
+ description: 'This endpoint updates an existing API key'
+ })
+ @ApiParam({
+ name: 'id',
+ description: 'API key ID',
+ required: true,
+ schema: { type: 'string' }
+ })
+ @ApiOkResponse({
+ schema: apiKeySchema,
+ description: 'API key updated successfully'
+ })
+ @ApiForbiddenResponse(invalidAuthenticationResponse)
  async updateApiKey(
  @CurrentUser() user: User,
  @Body() dto: UpdateApiKey,
@@ -37,21 +100,103 @@ export class ApiKeyController {
 
  @Delete(':id')
  @RequiredApiKeyAuthorities(Authority.DELETE_API_KEY)
+ @HttpCode(204)
+ @ApiOperation({
+ summary: 'Delete API key',
+ description: 'This endpoint deletes an existing API key'
+ })
+ @ApiParam({
+ name: 'id',
+ description: 'API key ID',
+ required: true,
+ schema: { type: 'string' }
+ })
+ @ApiNoContentResponse({
+ description: 'API key deleted successfully'
+ })
+ @ApiForbiddenResponse(invalidAuthenticationResponse)
  async deleteApiKey(@CurrentUser() user: User, @Param('id') id: string) {
  return this.apiKeyService.deleteApiKey(user, id)
  }
 
  @Get(':id')
  @RequiredApiKeyAuthorities(Authority.READ_API_KEY)
+ @ApiOperation({
+ summary: 'Get API key',
+ description: 'This endpoint returns the details of an API key'
+ })
+ @ApiParam({
+ name: 'id',
+ description: 'API key ID',
+ required: true,
+ schema: { type: 'string' }
+ })
+ @ApiOkResponse({
+ schema: apiKeySchemaWithValue,
+ description: 'API key details'
+ })
+ @ApiForbiddenResponse(invalidAuthenticationResponse)
  async getApiKey(@CurrentUser() user: User, @Param('id') id: string) {
  return this.apiKeyService.getApiKeyById(user, id)
  }
 
  @Get('all')
  @RequiredApiKeyAuthorities(Authority.READ_API_KEY)
+ @ApiOperation({
+ summary: 'Get all API keys',
+ description: 'This endpoint returns all API keys of the user'
+ })
+ @ApiQuery({
+ name: 'page',
+ description: 'Page number',
+ required: false,
+ type: Number,
+ example: 1,
+ allowEmptyValue: false
+ })
+ @ApiQuery({
+ name: 'limit',
+ description: 'Number of items per page',
+ required: false,
+ type: Number,
+ example: 10,
+ allowEmptyValue: false
+ })
+ @ApiQuery({
+ name: 'sort',
+ description: 'Sort by field',
+ required: false,
+ type: String,
+ example: 'name',
+ allowEmptyValue: false
+ })
+ @ApiQuery({
+ name: 'order',
+ description: 'Sort order',
+ required: false,
+ type: String,
+ example: 'asc',
+ allowEmptyValue: false
+ })
+ @ApiQuery({
+ name: 'search',
+ description: 'Search by name',
+ required: false,
+ type: String,
+ example: 'My API Key',
+ allowEmptyValue: false
+ })
+ @ApiOkResponse({
+ schema: {
+ type: 'array',
+ items: apiKeySchema
+ },
+ description: 'API keys'
+ })
+ @ApiForbiddenResponse(invalidAuthenticationResponse)
  async getApiKeysOfUser(
  @CurrentUser() user: User,
- @Query('page') page: number = 1,
+ @Query('page') page: number = 0,
  @Query('limit') limit: number = 10,
  @Query('sort') sort: string = 'name',
  @Query('order') order: string = 'asc',

apps/api/src/api-key/dto/create.api-key/create.api-key.ts

@@ -1,15 +1,39 @@
+import { ApiProperty } from '@nestjs/swagger'
 import { ApiKey, Authority } from '@prisma/client'
 import { IsArray, IsOptional, IsString } from 'class-validator'
 
 export class CreateApiKey {
  @IsString()
+ @ApiProperty({
+ name: 'name',
+ description: 'Name of the API key',
+ required: true,
+ type: String,
+ example: 'My API Key'
+ })
  name: ApiKey['name']
 
  @IsString()
  @IsOptional()
+ @ApiProperty({
+ name: 'expiresAfter',
+ description: 'API key expiration time in hours',
+ required: false,
+ type: String,
+ example: '24',
+ default: 'never'
+ })
  expiresAfter?: '24' | '168' | '720' | '8760' | 'never' = 'never'
 
  @IsArray()
  @IsOptional()
+ @ApiProperty({
+ name: 'authorities',
+ description: 'API key authorities',
+ required: false,
+ type: [String],
+ example: ['READ_SELF', 'UPDATE_SELF'],
+ default: []
+ })
  authorities?: Authority[] = []
 }

apps/api/src/api-key/service/api-key.service.ts

@@ -131,7 +131,7 @@ export class ApiKeyService {
  contains: search
  }
  },
- skip: (page - 1) * limit,
+ skip: page * limit,
  take: limit,
  orderBy: {
  [sort]: order