Files
dahyeon bb992167d2 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.
2025-11-10 15:42:02 +00:00

11 KiB

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 설치

# .NET 도구로 설치
dotnet tool install --global Microsoft.OpenApi.Kiota

# 또는 npm으로 설치
npm install -g @microsoft/kiota

API 클라이언트 생성

1. OpenAPI 스펙 다운로드

서버를 실행한 후:

# YAML 형식으로 다운로드 (권장)
curl http://localhost:3415/v1/api-yaml > openapi.yaml

# 또는 JSON 형식
curl http://localhost:3415/v1/api-json > openapi.json

2. Kiota로 클라이언트 생성

TypeScript/JavaScript 클라이언트

kiota generate \
  -l typescript \
  -d openapi.yaml \
  -c WikiApiClient \
  -o ./generated/typescript \
  --exclude-backward-compatible

C# 클라이언트

kiota generate \
  -l csharp \
  -d openapi.yaml \
  -c WikiApiClient \
  -n WikiApi.Client \
  -o ./generated/csharp

Java 클라이언트

kiota generate \
  -l java \
  -d openapi.yaml \
  -c WikiApiClient \
  -n com.wiki.client \
  -o ./generated/java

Python 클라이언트

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 클라이언트 사용

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# 클라이언트 사용

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 스펙 버전이 일치하는지 확인
  • 클라이언트를 재생성

추가 리소스