# 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)