Adds detailed `@ApiBody` schemas to several endpoints within `PageController` and `SpaceController`, including methods for creating and updating pages, spaces, and managing temporary access tokens. This provides clear, machine-readable descriptions of expected request bodies for API consumers. Enables the Swagger UI in the main application bootstrap, allowing for interactive exploration and testing of the API endpoints directly through the browser.
318 lines
11 KiB
TypeScript
318 lines
11 KiB
TypeScript
import { Controller, Post, Get, Put, Delete, Body, Param, Query, HttpCode, HttpStatus, UseGuards } from "@nestjs/common";
|
|
import {
|
|
ApiTags,
|
|
ApiOperation,
|
|
ApiResponse,
|
|
ApiParam,
|
|
ApiQuery,
|
|
ApiBody,
|
|
ApiBadRequestResponse,
|
|
ApiNotFoundResponse,
|
|
ApiConflictResponse,
|
|
ApiUnauthorizedResponse,
|
|
ApiBearerAuth
|
|
} from "@nestjs/swagger";
|
|
import {
|
|
SpaceService,
|
|
CreateSpaceDto,
|
|
UpdateSpaceDto,
|
|
SpaceResponseDto,
|
|
SpaceWithCreatorDto,
|
|
SpaceStatisticsDto,
|
|
DeleteSpaceResponseDto
|
|
} from "./space.service";
|
|
import { AllowPublicAccess } from "../global/auth/allow-public-access.decorator";
|
|
import { ExtractUserPayloadFromToken } from "../global/auth/extract-user-payload-from-token.decorator";
|
|
import { type EntraIDPayloadClaims } from "../global/auth/jwt.service";
|
|
import { JwtAuthGuard } from "../global/auth/jwt.guard";
|
|
|
|
@ApiTags('Space')
|
|
@UseGuards(JwtAuthGuard)
|
|
@Controller('space')
|
|
export class SpaceController {
|
|
constructor(private readonly spaceService: SpaceService) {}
|
|
|
|
/**
|
|
* POST /space - 스페이스 생성
|
|
*/
|
|
@Post()
|
|
@ApiBearerAuth()
|
|
@ApiOperation({
|
|
summary: '스페이스 생성',
|
|
description: '새로운 스페이스를 생성합니다. 스페이스 키는 고유해야 하며 URL에 사용됩니다. (인증 필요)'
|
|
})
|
|
@ApiBody({
|
|
description: '스페이스 생성 정보 (userId는 토큰에서 자동 추출)',
|
|
schema: {
|
|
type: 'object',
|
|
required: ['spaceKey', 'name'],
|
|
properties: {
|
|
spaceKey: {
|
|
type: 'string',
|
|
description: '스페이스 키 (고유 식별자, URL에 사용, 소문자/숫자/하이픈만 허용)',
|
|
pattern: '^[a-z0-9-]+$',
|
|
maxLength: 50,
|
|
example: 'engineering'
|
|
},
|
|
name: {
|
|
type: 'string',
|
|
description: '스페이스 이름',
|
|
maxLength: 255,
|
|
example: 'Engineering Team'
|
|
},
|
|
description: {
|
|
type: 'string',
|
|
description: '스페이스 설명',
|
|
example: 'Engineering team documentation and knowledge base'
|
|
}
|
|
}
|
|
}
|
|
})
|
|
@ApiResponse({
|
|
status: 201,
|
|
description: '스페이스가 성공적으로 생성됨',
|
|
type: SpaceResponseDto
|
|
})
|
|
@ApiBadRequestResponse({ description: '잘못된 요청 (스페이스 키 형식 오류 등)' })
|
|
@ApiNotFoundResponse({ description: '사용자를 찾을 수 없음' })
|
|
@ApiConflictResponse({ description: '스페이스 키가 이미 존재함' })
|
|
@ApiUnauthorizedResponse({ description: '인증 실패' })
|
|
async createSpace(
|
|
@Body() dto: Omit<CreateSpaceDto, 'userId'>,
|
|
@ExtractUserPayloadFromToken() user: EntraIDPayloadClaims
|
|
): Promise<SpaceResponseDto> {
|
|
return await this.spaceService.createSpace({
|
|
...dto,
|
|
userId: user.oid
|
|
}) as any;
|
|
}
|
|
|
|
/**
|
|
* GET /space - 모든 스페이스 조회
|
|
*/
|
|
@Get()
|
|
@AllowPublicAccess()
|
|
@ApiOperation({
|
|
summary: '모든 스페이스 조회',
|
|
description: '시스템의 모든 스페이스를 조회합니다. withCreator 파라미터로 생성자 정보 포함 여부를 선택할 수 있습니다. (공개 접근 가능)'
|
|
})
|
|
@ApiQuery({
|
|
name: 'withCreator',
|
|
required: false,
|
|
description: '생성자 정보 포함 여부',
|
|
type: Boolean
|
|
})
|
|
@ApiResponse({
|
|
status: 200,
|
|
description: '스페이스 목록 조회 성공',
|
|
type: SpaceResponseDto,
|
|
isArray: true
|
|
})
|
|
async getAllSpaces(
|
|
@Query('withCreator') withCreator?: boolean
|
|
): Promise<SpaceResponseDto[] | SpaceWithCreatorDto[]> {
|
|
if (withCreator) {
|
|
return await this.spaceService.getAllSpacesWithCreator() as any;
|
|
}
|
|
return await this.spaceService.getAllSpaces() as any;
|
|
}
|
|
|
|
/**
|
|
* GET /space/:spaceId - 스페이스 ID로 조회
|
|
*/
|
|
@Get(':spaceId')
|
|
@AllowPublicAccess()
|
|
@ApiOperation({
|
|
summary: '스페이스 ID로 조회',
|
|
description: '특정 스페이스를 ID로 조회합니다. withCreator 파라미터로 생성자 정보 포함 여부를 선택할 수 있습니다. (공개 접근 가능)'
|
|
})
|
|
@ApiParam({
|
|
name: 'spaceId',
|
|
description: '조회할 스페이스 ID',
|
|
type: String,
|
|
format: 'uuid'
|
|
})
|
|
@ApiQuery({
|
|
name: 'withCreator',
|
|
required: false,
|
|
description: '생성자 정보 포함 여부',
|
|
type: Boolean
|
|
})
|
|
@ApiResponse({
|
|
status: 200,
|
|
description: '스페이스 조회 성공',
|
|
type: SpaceResponseDto
|
|
})
|
|
@ApiNotFoundResponse({ description: '스페이스를 찾을 수 없음' })
|
|
async getSpaceById(
|
|
@Param('spaceId') spaceId: string,
|
|
@Query('withCreator') withCreator?: boolean
|
|
): Promise<SpaceResponseDto | SpaceWithCreatorDto> {
|
|
if (withCreator) {
|
|
return await this.spaceService.getSpaceWithCreator(spaceId) as any;
|
|
}
|
|
return await this.spaceService.getSpaceById(spaceId) as any;
|
|
}
|
|
|
|
/**
|
|
* GET /space/key/:spaceKey - 스페이스 키로 조회
|
|
*/
|
|
@Get('key/:spaceKey')
|
|
@AllowPublicAccess()
|
|
@ApiOperation({
|
|
summary: '스페이스 키로 조회',
|
|
description: '특정 스페이스를 키로 조회합니다. URL 친화적인 식별자로 사용됩니다. (공개 접근 가능)'
|
|
})
|
|
@ApiParam({
|
|
name: 'spaceKey',
|
|
description: '조회할 스페이스 키',
|
|
type: String,
|
|
example: 'engineering'
|
|
})
|
|
@ApiResponse({
|
|
status: 200,
|
|
description: '스페이스 조회 성공',
|
|
type: SpaceResponseDto
|
|
})
|
|
@ApiNotFoundResponse({ description: '스페이스를 찾을 수 없음' })
|
|
async getSpaceByKey(
|
|
@Param('spaceKey') spaceKey: string
|
|
): Promise<SpaceResponseDto> {
|
|
return await this.spaceService.getSpaceByKey(spaceKey) as any;
|
|
}
|
|
|
|
/**
|
|
* GET /space/:spaceId/statistics - 스페이스 통계 조회
|
|
*/
|
|
@Get(':spaceId/statistics')
|
|
@AllowPublicAccess()
|
|
@ApiOperation({
|
|
summary: '스페이스 통계 조회',
|
|
description: '스페이스의 통계 정보(전체 페이지 수, 루트 페이지 수 등)를 조회합니다. (공개 접근 가능)'
|
|
})
|
|
@ApiParam({
|
|
name: 'spaceId',
|
|
description: '통계를 조회할 스페이스 ID',
|
|
type: String,
|
|
format: 'uuid'
|
|
})
|
|
@ApiResponse({
|
|
status: 200,
|
|
description: '스페이스 통계 조회 성공',
|
|
type: SpaceStatisticsDto
|
|
})
|
|
@ApiNotFoundResponse({ description: '스페이스를 찾을 수 없음' })
|
|
async getSpaceStatistics(
|
|
@Param('spaceId') spaceId: string
|
|
): Promise<SpaceStatisticsDto> {
|
|
return await this.spaceService.getSpaceStatistics(spaceId) as any;
|
|
}
|
|
|
|
/**
|
|
* GET /space/user/:userId - 사용자가 생성한 스페이스 조회
|
|
*/
|
|
@Get('user/:userId')
|
|
@AllowPublicAccess()
|
|
@ApiOperation({
|
|
summary: '사용자가 생성한 스페이스 조회',
|
|
description: '특정 사용자가 생성한 모든 스페이스를 조회합니다. (공개 접근 가능)'
|
|
})
|
|
@ApiParam({
|
|
name: 'userId',
|
|
description: '사용자 ID',
|
|
type: String,
|
|
format: 'uuid'
|
|
})
|
|
@ApiResponse({
|
|
status: 200,
|
|
description: '사용자의 스페이스 목록 조회 성공',
|
|
type: SpaceResponseDto,
|
|
isArray: true
|
|
})
|
|
@ApiNotFoundResponse({ description: '사용자를 찾을 수 없음' })
|
|
async getSpacesByCreator(
|
|
@Param('userId') userId: string
|
|
): Promise<SpaceResponseDto[]> {
|
|
return await this.spaceService.getSpacesByCreator(userId) as any;
|
|
}
|
|
|
|
/**
|
|
* PUT /space/:spaceId - 스페이스 업데이트
|
|
*/
|
|
@Put(':spaceId')
|
|
@ApiBearerAuth()
|
|
@ApiOperation({
|
|
summary: '스페이스 업데이트',
|
|
description: '스페이스의 이름과 설명을 업데이트합니다. 스페이스 키는 변경할 수 없습니다. (인증 필요)'
|
|
})
|
|
@ApiParam({
|
|
name: 'spaceId',
|
|
description: '업데이트할 스페이스 ID',
|
|
type: String,
|
|
format: 'uuid'
|
|
})
|
|
@ApiBody({
|
|
description: '스페이스 업데이트 정보 (모든 필드 선택사항)',
|
|
schema: {
|
|
type: 'object',
|
|
properties: {
|
|
name: {
|
|
type: 'string',
|
|
description: '스페이스 이름',
|
|
maxLength: 255,
|
|
example: 'Updated Team Name'
|
|
},
|
|
description: {
|
|
type: 'string',
|
|
description: '스페이스 설명',
|
|
example: 'Updated description for the team'
|
|
}
|
|
}
|
|
}
|
|
})
|
|
@ApiResponse({
|
|
status: 200,
|
|
description: '스페이스가 성공적으로 업데이트됨',
|
|
type: SpaceResponseDto
|
|
})
|
|
@ApiNotFoundResponse({ description: '스페이스를 찾을 수 없음' })
|
|
@ApiUnauthorizedResponse({ description: '인증 실패' })
|
|
async updateSpace(
|
|
@Param('spaceId') spaceId: string,
|
|
@Body() dto: UpdateSpaceDto,
|
|
@ExtractUserPayloadFromToken() user: EntraIDPayloadClaims
|
|
): Promise<SpaceResponseDto> {
|
|
return await this.spaceService.updateSpace(spaceId, dto) as any;
|
|
}
|
|
|
|
/**
|
|
* DELETE /space/:spaceId - 스페이스 삭제
|
|
*/
|
|
@Delete(':spaceId')
|
|
@HttpCode(HttpStatus.OK)
|
|
@ApiBearerAuth()
|
|
@ApiOperation({
|
|
summary: '스페이스 삭제',
|
|
description: '스페이스를 삭제합니다. CASCADE 설정으로 해당 스페이스의 모든 페이지도 함께 삭제됩니다. (인증 필요)'
|
|
})
|
|
@ApiParam({
|
|
name: 'spaceId',
|
|
description: '삭제할 스페이스 ID',
|
|
type: String,
|
|
format: 'uuid'
|
|
})
|
|
@ApiResponse({
|
|
status: 200,
|
|
description: '스페이스가 성공적으로 삭제됨',
|
|
type: DeleteSpaceResponseDto
|
|
})
|
|
@ApiNotFoundResponse({ description: '스페이스를 찾을 수 없음' })
|
|
@ApiUnauthorizedResponse({ description: '인증 실패' })
|
|
async deleteSpace(
|
|
@Param('spaceId') spaceId: string,
|
|
@ExtractUserPayloadFromToken() user: EntraIDPayloadClaims
|
|
): Promise<DeleteSpaceResponseDto> {
|
|
return await this.spaceService.deleteSpace(spaceId) as any;
|
|
}
|
|
}
|