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.
11 KiB
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:
CreateSpaceDtospaceKey(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:
UpdateSpaceDtoname(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:
CreatePageDtospaceId(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:
UpdatePageDtotitle(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:
DeletePageDtouserId(uuid, required)
- Response:
DeleteResponseDto
5. POST /v1/page/temporary-access-token - 토큰 생성
- Request:
CreateTemporaryTokenDtopageIds(uuid[], optional) - 권한을 부여할 페이지 ID 배열spaceIds(uuid[], optional) - 권한을 부여할 스페이스 ID 배열expiresInHours(number, optional, min: 1)description(string, optional, max 255)userId(uuid, required)
- Response:
CreateTokenResponseDtotoken:TokenInfoDtopermissions:TokenPermissionsDto
6. DELETE /v1/page/temporary-access-token - 토큰 삭제
- Request:
DeleteTokenDtotokenValue(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 스펙 버전이 일치하는지 확인
- 클라이언트를 재생성