Adds comprehensive page management and temporary access tokens

Introduces the `PageModule` to provide full CRUD capabilities for pages within spaces.

Key features include:
-   API endpoints for creating, retrieving, updating, and soft-deleting pages.
-   Support for hierarchical page structures with validation to prevent circular references.
-   A mechanism to generate and manage temporary access tokens, allowing controlled public access to specific pages or entire spaces.
-   Integration with database repositories and comprehensive Swagger documentation for all new endpoints and DTOs.
-   Ensures proper authorization and validation for all page and token operations.
This commit is contained in:
dahyeon committed 2025-11-10 15:42:02 +00:00
1 parent ef440a2dbd
commit bb992167d2
10 files changed
+2315 -5

No files matched your search

+382
View File
@@ -0,0 +1,382 @@
# Kiota API Client 생성 가이드
이 문서는 Swagger/OpenAPI 스펙으로부터 Kiota를 사용하여 타입 안전한 API 클라이언트를 생성하는 방법을 설명합니다.
## Swagger 문서 접근
서버가 개발 또는 테스트 모드로 실행 중일 때:
- **Swagger UI**: `http://localhost:3415/v1/api` (UI는 비활성화됨)
- **OpenAPI YAML**: `http://localhost:3415/v1/api-yaml`
- **OpenAPI JSON**: `http://localhost:3415/v1/api-json`
## Kiota 설치
```bash
# .NET 도구로 설치
dotnet tool install --global Microsoft.OpenApi.Kiota
# 또는 npm으로 설치
npm install -g @microsoft/kiota
```
## API 클라이언트 생성
### 1. OpenAPI 스펙 다운로드
서버를 실행한 후:
```bash
# YAML 형식으로 다운로드 (권장)
curl http://localhost:3415/v1/api-yaml > openapi.yaml
# 또는 JSON 형식
curl http://localhost:3415/v1/api-json > openapi.json
```
### 2. Kiota로 클라이언트 생성
#### TypeScript/JavaScript 클라이언트
```bash
kiota generate \
-l typescript \
-d openapi.yaml \
-c WikiApiClient \
-o ./generated/typescript \
--exclude-backward-compatible
```
#### C# 클라이언트
```bash
kiota generate \
-l csharp \
-d openapi.yaml \
-c WikiApiClient \
-n WikiApi.Client \
-o ./generated/csharp
```
#### Java 클라이언트
```bash
kiota generate \
-l java \
-d openapi.yaml \
-c WikiApiClient \
-n com.wiki.client \
-o ./generated/java
```
#### Python 클라이언트
```bash
kiota generate \
-l python \
-d openapi.yaml \
-c WikiApiClient \
-n wiki_api_client \
-o ./generated/python
```
## API 엔드포인트 구조
생성된 클라이언트는 다음 엔드포인트를 포함합니다:
### Space API (`/v1/space`)
모든 엔드포인트는 `@ApiTags('Space')` 태그로 그룹화됩니다.
#### 1. POST /v1/space - 스페이스 생성
- **Request**: `CreateSpaceDto`
- `spaceKey` (string, required, pattern: ^[a-z0-9-]+$, max 50)
- `name` (string, required, max 255)
- `description` (string, optional)
- `userId` (uuid, required)
- **Response**: `SpaceResponseDto`
#### 2. GET /v1/space - 모든 스페이스 조회
- **Query Parameters**:
- `withCreator` (boolean, optional) - 생성자 정보 포함 여부
- **Response**: `SpaceResponseDto[]` 또는 `SpaceWithCreatorDto[]`
#### 3. GET /v1/space/{spaceId} - 스페이스 ID로 조회
- **Path Parameter**: `spaceId` (uuid)
- **Query Parameters**:
- `withCreator` (boolean, optional)
- **Response**: `SpaceResponseDto` 또는 `SpaceWithCreatorDto`
#### 4. GET /v1/space/key/{spaceKey} - 스페이스 키로 조회
- **Path Parameter**: `spaceKey` (string)
- **Response**: `SpaceResponseDto`
#### 5. GET /v1/space/{spaceId}/statistics - 스페이스 통계
- **Path Parameter**: `spaceId` (uuid)
- **Response**: `SpaceStatisticsDto`
#### 6. GET /v1/space/user/{userId} - 사용자의 스페이스 목록
- **Path Parameter**: `userId` (uuid)
- **Response**: `SpaceResponseDto[]`
#### 7. PUT /v1/space/{spaceId} - 스페이스 업데이트
- **Path Parameter**: `spaceId` (uuid)
- **Request**: `UpdateSpaceDto`
- `name` (string, optional)
- `description` (string, optional)
- **Response**: `SpaceResponseDto`
#### 8. DELETE /v1/space/{spaceId} - 스페이스 삭제
- **Path Parameter**: `spaceId` (uuid)
- **Response**: `DeleteSpaceResponseDto`
- **Warning**: CASCADE로 모든 페이지도 삭제됨
---
### Page API (`/v1/page`)
모든 엔드포인트는 `@ApiTags('Page')` 태그로 그룹화됩니다.
#### 1. POST /v1/page - 페이지 생성
- **Request**: `CreatePageDto`
- `spaceId` (uuid, required)
- `parentPageId` (uuid, optional)
- `title` (string, required, max 255)
- `content` (string, optional)
- `userId` (uuid, required)
- `sortOrder` (number, optional, default: 0)
- **Response**: `PageResponseDto`
#### 2. GET /v1/page - 페이지 조회
- **Query Parameters**:
- `pageId` (uuid, optional) - 특정 페이지 조회
- `spaceId` (uuid, optional) - 스페이스의 모든 페이지 조회
- **Response**: `PageResponseDto` 또는 `PageResponseDto[]`
#### 3. PUT /v1/page/{pageId} - 페이지 업데이트
- **Path Parameter**: `pageId` (uuid)
- **Request**: `UpdatePageDto`
- `title` (string, optional)
- `content` (string, optional)
- `parentPageId` (uuid, optional, nullable)
- `sortOrder` (number, optional)
- `userId` (uuid, required)
- **Response**: `PageResponseDto`
#### 4. DELETE /v1/page/{pageId} - 페이지 삭제
- **Path Parameter**: `pageId` (uuid)
- **Request**: `DeletePageDto`
- `userId` (uuid, required)
- **Response**: `DeleteResponseDto`
#### 5. POST /v1/page/temporary-access-token - 토큰 생성
- **Request**: `CreateTemporaryTokenDto`
- `pageIds` (uuid[], optional) - 권한을 부여할 페이지 ID 배열
- `spaceIds` (uuid[], optional) - 권한을 부여할 스페이스 ID 배열
- `expiresInHours` (number, optional, min: 1)
- `description` (string, optional, max 255)
- `userId` (uuid, required)
- **Response**: `CreateTokenResponseDto`
- `token`: `TokenInfoDto`
- `permissions`: `TokenPermissionsDto`
#### 6. DELETE /v1/page/temporary-access-token - 토큰 삭제
- **Request**: `DeleteTokenDto`
- `tokenValue` (string, required)
- `userId` (uuid, required)
- **Response**: `DeleteResponseDto`
## 사용 예제
### TypeScript 클라이언트 사용
```typescript
import { WikiApiClient } from './generated/typescript';
import { FetchRequestAdapter } from '@microsoft/kiota-http-fetchlibrary';
// 클라이언트 초기화
const adapter = new FetchRequestAdapter();
adapter.baseUrl = 'http://localhost:3415/v1';
const client = new WikiApiClient(adapter);
// 스페이스 생성
const newSpace = await client.space.post({
spaceKey: 'engineering',
name: 'Engineering Team',
description: 'Engineering documentation',
userId: '550e8400-e29b-41d4-a716-446655440001'
});
// 스페이스 조회 (키로)
const space = await client.space.key.bySpaceKey('engineering').get();
// 모든 스페이스 조회 (생성자 정보 포함)
const allSpaces = await client.space.get({
queryParameters: {
withCreator: true
}
});
// 페이지 생성
const newPage = await client.page.post({
spaceId: newSpace.spaceId,
title: 'My New Page',
content: '# Welcome\n\nThis is my page.',
userId: '550e8400-e29b-41d4-a716-446655440001'
});
// 페이지 조회
const page = await client.page.get({
queryParameters: {
pageId: newPage.pageId
}
});
// 페이지 업데이트
const updatedPage = await client.page.byPageId(newPage.pageId).put({
title: 'Updated Title',
content: '# Updated\n\nNew content.',
userId: '550e8400-e29b-41d4-a716-446655440001'
});
// 임시 토큰 생성
const tokenResponse = await client.page.temporaryAccessToken.post({
pageIds: [newPage.pageId],
expiresInHours: 24,
description: '24시간 공유 링크',
userId: '550e8400-e29b-41d4-a716-446655440001'
});
console.log('Token:', tokenResponse.token.tokenValue);
// 토큰 삭제
await client.page.temporaryAccessToken.delete({
tokenValue: tokenResponse.token.tokenValue,
userId: '550e8400-e29b-41d4-a716-446655440001'
});
// 페이지 삭제
await client.page.byPageId(newPage.pageId).delete({
userId: '550e8400-e29b-41d4-a716-446655440001'
});
```
### C# 클라이언트 사용
```csharp
using WikiApi.Client;
using Microsoft.Kiota.Http.HttpClientLibrary;
// 클라이언트 초기화
var adapter = new HttpClientRequestAdapter(authProvider);
adapter.BaseUrl = "http://localhost:3415/v1";
var client = new WikiApiClient(adapter);
// 스페이스 생성
var newSpace = await client.Space.PostAsync(new CreateSpaceDto
{
SpaceKey = "engineering",
Name = "Engineering Team",
Description = "Engineering documentation",
UserId = "550e8400-e29b-41d4-a716-446655440001"
});
// 스페이스 조회 (키로)
var space = await client.Space.Key["engineering"].GetAsync();
// 스페이스 통계 조회
var statistics = await client.Space[newSpace.SpaceId].Statistics.GetAsync();
// 페이지 생성
var newPage = await client.Page.PostAsync(new CreatePageDto
{
SpaceId = newSpace.SpaceId,
Title = "My New Page",
Content = "# Welcome\n\nThis is my page.",
UserId = "550e8400-e29b-41d4-a716-446655440001"
});
// 페이지 조회
var page = await client.Page.GetAsync(config =>
{
config.QueryParameters.PageId = newPage.PageId;
});
// 페이지 업데이트
var updatedPage = await client.Page[newPage.PageId].PutAsync(new UpdatePageDto
{
Title = "Updated Title",
Content = "# Updated\n\nNew content.",
UserId = "550e8400-e29b-41d4-a716-446655440001"
});
// 임시 토큰 생성
var tokenResponse = await client.Page.TemporaryAccessToken.PostAsync(new CreateTemporaryTokenDto
{
PageIds = new[] { newPage.PageId },
ExpiresInHours = 24,
Description = "24시간 공유 링크",
UserId = "550e8400-e29b-41d4-a716-446655440001"
});
Console.WriteLine($"Token: {tokenResponse.Token.TokenValue}");
// 토큰 삭제
await client.Page.TemporaryAccessToken.DeleteAsync(new DeleteTokenDto
{
TokenValue = tokenResponse.Token.TokenValue,
UserId = "550e8400-e29b-41d4-a716-446655440001"
});
// 페이지 삭제
await client.Page[newPage.PageId].DeleteAsync(new DeletePageDto
{
UserId = "550e8400-e29b-41d4-a716-446655440001"
});
```
## 타입 안전성
Kiota로 생성된 클라이언트는 완전한 타입 안전성을 제공합니다:
- ✅ 모든 DTO에 대한 타입 정의
- ✅ UUID 형식 검증
- ✅ 필수/선택 필드 구분
- ✅ 배열 타입 지원
- ✅ Nullable 타입 지원
- ✅ 에러 응답 타입 정의
- ✅ 자동 완성 지원
## 주요 특징
### 1. 토큰 권한 모델
토큰은 여러 페이지와 스페이스에 대한 권한을 배열로 가질 수 있습니다:
- `pageIds`: 특정 페이지들에 대한 직접 접근 권한
- `spaceIds`: 스페이스 내 모든 페이지에 대한 접근 권한
### 2. 계층 구조
페이지는 부모-자식 관계를 가질 수 있으며, 순환 참조가 자동으로 방지됩니다.
### 3. 소프트 삭제
페이지 삭제는 소프트 삭제로 처리되어 복구가 가능합니다.
## 문제 해결
### OpenAPI 스펙이 다운로드되지 않는 경우
- 서버가 `dev` 또는 `test` 모드로 실행 중인지 확인
- `NODE_ENV` 환경 변수 확인
### Kiota 생성 오류
- OpenAPI 스펙이 유효한지 확인: https://editor.swagger.io/
- Kiota 버전 확인: `kiota --version`
- 최신 버전으로 업데이트: `dotnet tool update --global Microsoft.OpenApi.Kiota`
### 타입 불일치 오류
- 서버와 클라이언트의 OpenAPI 스펙 버전이 일치하는지 확인
- 클라이언트를 재생성
## 추가 리소스
- [Kiota 공식 문서](https://learn.microsoft.com/en-us/openapi/kiota/)
- [OpenAPI 스펙](https://swagger.io/specification/)
- [NestJS Swagger](https://docs.nestjs.com/openapi/introduction)