皆さんこんにちは。
エンジニアの星加です。
今回はOpenAPI定義書からAPIクライアントを生成できるKiotaというツールをご紹介します！
C#のコードが生成できるAPIクライアントジェネレータは数が少ないため、参考になればと思います。
目次
Kiotaとは？
Microsoftが開発する、OpenAPI定義書からAPIクライアントを自動生成するコマンドラインツールです。
HTTP APIを呼び出すための高品質なAPIクライアントを簡単に実装することができます。
Kiotaの主な特徴
ドキュメントでは以下のように紹介されています。
- C#、Go、Java、PHP、Python、Ruby、TypeScriptなど幅広い言語への対応。
- OpenAPI定義書を基に、リクエスト・レスポンスの型付け、シリアライズ・デシリアライズの処理を自動生成。
- Kiotaのコアライブラリに依存することで、不要部分を省き必要最小限のコードのみを生成。
- HTTP制御（認証、ミドルウェア、ヘッダー設定など）にも完全対応。
- API仕様から必要なエンドポイントやモデルのみ選んで生成可能。
KiotaでAPIクライアントを作ろう
今回は公式ドキュメントのC#向けQuickStartを参考に、C#向けのAPIクライアントを作成してみたいと思います。
対象とするAPIは、「JSONPlaceholder」という無料のテスト用APIを利用します。
jsonplaceholder.typicode.com
事前に準備するもの
- .NET 10 SDK
- お好みのエディタ（Visual Studioを推奨）
１． APIクライアントを生成する
１-１． プロジェクトの準備
まずはAPIクライアントを作成するためのプロジェクトを準備します。
今回はクラスライブラリとして作成します。
１． ソリューションを作成します。
dotnet new sln --output KiotaExample --format slnx cd KiotaExample
２． クラスライブラリプロジェクトを作成し、ソリューションに追加します。
dotnet new classlib -o JsonPlaceholder dotnet sln add ./JsonPlaceholder/JsonPlaceholder.csproj cd JsonPlaceholder
３． Microsoft.Kiota.Bundle を依存関係に追加します。
dotnet add package Microsoft.Kiota.Bundle
４． KiotaExample/JsonPlaceholder/ 配下にある Class1.cs を削除します。
５． KiotaExample/JsonPlaceholder/ 配下に openapi.yml を作成し、以下を記入します。
openapi: '3.0.2' info: title: JSONPlaceholder version: '1.0' servers: - url: https://jsonplaceholder.typicode.com/ components: schemas: post: type: object properties: userId: type: integer id: type: integer title: type: string body: type: string parameters: post-id: name: post-id in: path description: 'key: id of post' required: true style: simple schema: type: integer paths: /posts: get: description: Get posts parameters: - name: userId in: query description: Filter results by user ID required: false style: form schema: type: integer maxItems: 1 - name: title in: query description: Filter results by title required: false style: form schema: type: string maxItems: 1 responses: '200': description: OK content: application/json: schema: type: array items: $ref: '#/components/schemas/post' post: description: 'Create post' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/post' responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/post' /posts/{post-id}: get: description: 'Get post by ID' parameters: - $ref: '#/components/parameters/post-id' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/post' patch: description: 'Update post' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/post' parameters: - $ref: '#/components/parameters/post-id' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/post' delete: description: 'Delete post' parameters: - $ref: '#/components/parameters/post-id' responses: '200': description: OK
OpenAPI仕様書は以下から引用しています。
６． プロジェクト構造を確認し、以下構造になっていればプロジェクトの準備は完了です。
📂 KiotaExample ├─ 📄 KiotaExample.slnx └─ 📂 JsonPlaceholder ├─ 📄 JsonPlaceholder.csproj └─ 📄 openapi.yml
１-２． APIクライアントの生成
プロジェクトが準備できたので、KiotaでAPIクライアントを生成します。
１． Kiotaの.NETツールをインストールします。
dotnet tool install --global Microsoft.OpenApi.Kiota
２． APIクライアントを生成します。
kiota generate -l CSharp -c JsonPlaceholderClient -n JsonPlaceholder -d ./openapi.yml -o ./
引数はそれぞれ以下の値を指定しています。
| 引数 | 説明 |
|---|---|
| -l | 使用する言語 |
| -c | メインクラス名 |
| -n | 名前空間 |
| -d | APIクライアントの基となるOpenAPI定義書 |
| -o | 出力先ディレクトリ |
以下のログが表示されたら生成完了です。
Generation completed successfully Client base url set to https://jsonplaceholder.typicode.com
３． プロジェクト構造を確認し、生成されたAPIクライアントを確認します。
正常に生成できている場合、以下の構造になります。
📂 KiotaExample
├─ 📄 KiotaExample.slnx
└─ 📂 JsonPlaceholder
├─ 📄 JsonPlaceholderClient.cs
├─ 📄 JsonPlaceholder.csproj
├─ 📄 kiota-lock.json
├─ 📄 openapi.yml
├─ 📂 Models
│ ├─ 📄 Post.cs
└─ 📂 Posts
├─ 📄 PostsRequestBuilder.cs
└─ 📂 Item
└─ 📄 PostItemRequestBuilder.cs
２． APIクライアントを使用する
２-１. プロジェクトの準備
Kiotaで生成したクライアントを利用するために、コンソールアプリを準備します。
１． プロジェクトのルートディレクトリ（KiotaExample/）に戻り、コンソールアプリを作成しソリューションに追加します。
dotnet new console -o Example dotnet sln add ./Example/Example.csproj cd Example
２． Example.csproj に以下を記入します。
<Project Sdk="Microsoft.NET.Sdk"> <PropertyGroup> <OutputType>Exe</OutputType> <TargetFramework>net10.0</TargetFramework> <ImplicitUsings>enable</ImplicitUsings> <Nullable>enable</Nullable> </PropertyGroup> <ItemGroup> <ProjectReference Include="..\JsonPlaceholder\JsonPlaceholder.csproj" /> </ItemGroup> </Project>
３． プロジェクト構造を確認し、以下構造になっていればプロジェクトの準備は完了です。
📂 KiotaExample ├─ 📄 KiotaExample.slnx ├─ 📂 JsonPlaceholder └─ 📂 Example ├─ 📄 Example.csproj └─ 📄 Program.cs
２-２． APIクライアントの使用
Kiotaで生成したAPIクライアントは、一般的なSDKのようにAPIクライアントのインスタンスを作成して使用します。
APIクライアントのインスタンスを生成するには、以下の構文を利用します。
var authenticationProvider = new AnonymousAuthenticationProvider(); var requestAdapter = new HttpClientRequestAdapter(authenticationProvider); var client = new JsonPlaceholderClient(requestAdapter);
今回は認証不要のAPIであるため、AnonymousAuthenticationProviderを使用しています。
実際のプロダクトでは認証が必要な場合が多いため、認証プロバイダを実装する必要があります。
詳細は以下のドキュメントをご確認ください。
learn.microsoft.com
各リクエストを送るには、以下の構文を使用します。
かなり分かりやすく実装されているため、直感的に利用することが可能です。
GET リクエスト
// GET /posts var response = await client.Posts.GetAsync(); // GET /posts/{id} var id = 1; var response = await client.Posts[id].GetAsync();
POST リクエスト
// POST /posts var requestBody = new Post { UserId = 1, Title = "Test Title", Body = "Test Body" }; var response = await client.Posts.PostAsync(requestBody);
PATCH リクエスト
// PATCH /posts/{id} var id = 1; var requestBody = new Post { Title = "Updated Title" }; var response = await client.Posts[id].PatchAsync(requestBody);
DELETE リクエスト
// DELETE /posts/{id} var id = 1; await client.Posts[id].DeleteAsync();
２-３． リクエストの送信
Program.cs にリクエストの送信処理を実装し、実際にリクエストが送れるかを確認します。
１． Program.cs に以下を記入します。
using JsonPlaceholder; using JsonPlaceholder.Models; using Microsoft.Kiota.Abstractions.Authentication; using Microsoft.Kiota.Http.HttpClientLibrary; var authenticationProvider = new AnonymousAuthenticationProvider(); var requestAdapter = new HttpClientRequestAdapter(authenticationProvider); var client = new JsonPlaceholderClient(requestAdapter); var id = 1; var postBody = new Post { UserId = 1, Title = "Test Title", Body = "Test Body" }; var patchBody = new Post { Title = "Updated Title" }; try { // GET /posts var getPosts = await client.Posts.GetAsync(); // GET /posts/{id} var getPost = await client.Posts[id].GetAsync(); // POST /posts var postPost = await client.Posts.PostAsync(postBody); // PATCH /posts/{id} var patchPost = await client.Posts[id].PatchAsync(patchBody); // DELETE /posts/{id} await client.Posts[id].DeleteAsync(); Console.WriteLine($"GET /posts\n- Count: {getPosts?.Count}\n"); Console.WriteLine($"GET /posts/id\n- Id: {getPost?.Id}\n- Title: {getPost?.Title}\n"); Console.WriteLine($"POST /posts/id\n- Id: {postPost?.Id}\n- Title: {postPost?.Title}\n"); Console.WriteLine($"PATCH /posts/id\n- Id: {patchPost?.Id}\n- Title: {patchPost?.Title}\n"); } catch (Exception ex) { Console.WriteLine(ex); }
２． コンソールアプリをビルドし、実行します。
dotnet build dotnet run
３． リクエストの結果を確認します。
以下が表示されていれば正常に処理されています。
GET /posts - Count: 100 GET /posts/id - Id: 1 - Title: sunt aut facere repellat provident occaecati excepturi optio reprehenderit POST /posts/id - Id: 101 - Title: Test Title PATCH /posts/id - Id: 1 - Title: Updated Title
おわりに
Kiotaを使用することで、OpenAPI定義書から型安全なAPIクライアントを簡単に自動生成できることが分かりました。
生成されるクライアントは直感的で使いやすく、リクエスト・レスポンスの型付けやシリアライズ処理の実装も自動で行われます。
C#をはじめ、複数の言語に対応しているため、マルチプラットフォームな開発環境でも活用できるでしょう。
素早くAPIクライアントを実装したい場合は、ぜひKiotaを使ってみてはいかがでしょうか。
サービス一覧 www.alterbooth.com cloudpointer.tech www.alterbooth.com
