Enhances API documentation and enables Swagger UI

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.
This commit is contained in:
dahyeon committed 2025-11-10 16:29:42 +00:00
1 parent bb992167d2
commit 4ec9bf1acf
3 files changed
+171 -1

No files matched your search

+1 -1
View File
@@ -19,7 +19,7 @@ async function bootstrap() {
}) })
.build(); .build();
const options: SwaggerCustomOptions = { const options: SwaggerCustomOptions = {
ui: false, ui: true,
raw: ['yaml'], raw: ['yaml'],
} }
const documentFactory = () => SwaggerModule.createDocument(app, config); const documentFactory = () => SwaggerModule.createDocument(app, config);
+123
View File
@@ -5,6 +5,7 @@ import {
ApiResponse, ApiResponse,
ApiParam, ApiParam,
ApiQuery, ApiQuery,
ApiBody,
ApiBadRequestResponse, ApiBadRequestResponse,
ApiNotFoundResponse, ApiNotFoundResponse,
ApiUnauthorizedResponse, ApiUnauthorizedResponse,
@@ -42,6 +43,45 @@ export class PageController {
summary: '페이지 생성', summary: '페이지 생성',
description: '새로운 페이지를 생성합니다. 스페이스 내에서 계층 구조를 가질 수 있습니다. (인증 필요)' description: '새로운 페이지를 생성합니다. 스페이스 내에서 계층 구조를 가질 수 있습니다. (인증 필요)'
}) })
@ApiBody({
description: '페이지 생성 정보 (userId는 토큰에서 자동 추출)',
schema: {
type: 'object',
required: ['spaceId', 'title'],
properties: {
spaceId: {
type: 'string',
format: 'uuid',
description: '페이지가 속할 스페이스 ID',
example: '550e8400-e29b-41d4-a716-446655440000'
},
parentPageId: {
type: 'string',
format: 'uuid',
description: '부모 페이지 ID (선택사항)',
example: '550e8400-e29b-41d4-a716-446655440001',
nullable: true
},
title: {
type: 'string',
description: '페이지 제목',
maxLength: 255,
example: 'Getting Started'
},
content: {
type: 'string',
description: '페이지 내용 (Markdown)',
example: '# Welcome\n\nThis is the getting started guide.'
},
sortOrder: {
type: 'number',
description: '정렬 순서',
default: 0,
example: 0
}
}
}
})
@ApiResponse({ @ApiResponse({
status: 201, status: 201,
description: '페이지가 성공적으로 생성됨', description: '페이지가 성공적으로 생성됨',
@@ -111,6 +151,37 @@ export class PageController {
type: String, type: String,
format: 'uuid' format: 'uuid'
}) })
@ApiBody({
description: '페이지 업데이트 정보 (모든 필드 선택사항, userId는 토큰에서 자동 추출)',
schema: {
type: 'object',
properties: {
title: {
type: 'string',
description: '페이지 제목',
maxLength: 255,
example: 'Updated Title'
},
content: {
type: 'string',
description: '페이지 내용 (Markdown)',
example: '# Updated\n\nNew content here.'
},
parentPageId: {
type: 'string',
format: 'uuid',
description: '부모 페이지 ID (null로 설정하면 루트 페이지가 됨)',
example: '550e8400-e29b-41d4-a716-446655440001',
nullable: true
},
sortOrder: {
type: 'number',
description: '정렬 순서',
example: 1
}
}
}
})
@ApiResponse({ @ApiResponse({
status: 200, status: 200,
description: '페이지가 성공적으로 업데이트됨', description: '페이지가 성공적으로 업데이트됨',
@@ -169,6 +240,44 @@ export class PageController {
summary: '임시 액세스 토큰 생성', summary: '임시 액세스 토큰 생성',
description: '특정 페이지 또는 스페이스에 대한 접근 권한을 가진 임시 토큰을 생성합니다. 토큰은 여러 페이지/스페이스에 대한 권한을 배열로 가질 수 있습니다. (인증 필요)' description: '특정 페이지 또는 스페이스에 대한 접근 권한을 가진 임시 토큰을 생성합니다. 토큰은 여러 페이지/스페이스에 대한 권한을 배열로 가질 수 있습니다. (인증 필요)'
}) })
@ApiBody({
description: '토큰 생성 정보 (pageIds 또는 spaceIds 중 최소 하나 필수, userId는 토큰에서 자동 추출)',
schema: {
type: 'object',
properties: {
pageIds: {
type: 'array',
items: {
type: 'string',
format: 'uuid'
},
description: '접근 권한을 부여할 페이지 ID 배열',
example: ['550e8400-e29b-41d4-a716-446655440000', '550e8400-e29b-41d4-a716-446655440001']
},
spaceIds: {
type: 'array',
items: {
type: 'string',
format: 'uuid'
},
description: '접근 권한을 부여할 스페이스 ID 배열',
example: ['550e8400-e29b-41d4-a716-446655440002']
},
expiresInHours: {
type: 'number',
description: '토큰 만료 시간 (시간 단위)',
minimum: 1,
example: 24
},
description: {
type: 'string',
description: '토큰 설명',
maxLength: 255,
example: '24시간 공유 링크'
}
}
}
})
@ApiResponse({ @ApiResponse({
status: 201, status: 201,
description: '토큰이 성공적으로 생성됨', description: '토큰이 성공적으로 생성됨',
@@ -197,6 +306,20 @@ export class PageController {
summary: '임시 액세스 토큰 삭제', summary: '임시 액세스 토큰 삭제',
description: '임시 액세스 토큰을 삭제합니다. 토큰 생성자만 삭제할 수 있습니다. (인증 필요)' description: '임시 액세스 토큰을 삭제합니다. 토큰 생성자만 삭제할 수 있습니다. (인증 필요)'
}) })
@ApiBody({
description: '삭제할 토큰 정보 (userId는 토큰에서 자동 추출)',
schema: {
type: 'object',
required: ['tokenValue'],
properties: {
tokenValue: {
type: 'string',
description: '삭제할 토큰 값',
example: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
}
}
}
})
@ApiResponse({ @ApiResponse({
status: 200, status: 200,
description: '토큰이 성공적으로 삭제됨', description: '토큰이 성공적으로 삭제됨',
+47
View File
@@ -5,6 +5,7 @@ import {
ApiResponse, ApiResponse,
ApiParam, ApiParam,
ApiQuery, ApiQuery,
ApiBody,
ApiBadRequestResponse, ApiBadRequestResponse,
ApiNotFoundResponse, ApiNotFoundResponse,
ApiConflictResponse, ApiConflictResponse,
@@ -40,6 +41,33 @@ export class SpaceController {
summary: '스페이스 생성', summary: '스페이스 생성',
description: '새로운 스페이스를 생성합니다. 스페이스 키는 고유해야 하며 URL에 사용됩니다. (인증 필요)' 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({ @ApiResponse({
status: 201, status: 201,
description: '스페이스가 성공적으로 생성됨', description: '스페이스가 성공적으로 생성됨',
@@ -223,6 +251,25 @@ export class SpaceController {
type: String, type: String,
format: 'uuid' 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({ @ApiResponse({
status: 200, status: 200,
description: '스페이스가 성공적으로 업데이트됨', description: '스페이스가 성공적으로 업데이트됨',