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.
383 lines
11 KiB
Markdown
383 lines
11 KiB
Markdown
# 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)
|