はじめに

前提条件

• .NET SDK 8.0 以降
• JSON または YAML 形式の OpenAPI 3.0-3.2 ドキュメント

1. パッケージをインストールする

次のいずれかの方法で、プロジェクトに NuGet パッケージを追加します。

.NET CLI

dotnet add package OpenApiWeaver --version x.y.z

Package Manager Console

Install-Package OpenApiWeaver -Version x.y.z

PackageReference

<ItemGroup>
  <PackageReference Include="OpenApiWeaver" Version="x.y.z" PrivateAssets="all" />
</ItemGroup>

NOTE

PrivateAssets="all" を指定すると、ソースジェネレーターはビルド時にのみ使用され、プロジェクトの推移的依存関係として公開されません。CLI や Package Manager Console でインストールした場合は、生成された PackageReference に PrivateAssets="all" を手動で追加してください。

2. OpenAPI ドキュメントを追加する

推奨: OpenApiWeaverDocument

任意のメタデータ付きで OpenAPI ドキュメントを含めるには、OpenApiWeaverDocument アイテムを使います。

<ItemGroup>
  <OpenApiWeaverDocument Include="openapi\petstore.yaml"
                         ClientName="PetstoreClient"
                         Namespace="Contoso.Generated" />
</ItemGroup>

Metadata	Required	Default
ClientName	No	ファイル名から導出 (petstore.yaml → PetstoreClient)
Namespace	No	プロジェクトの RootNamespace

AdditionalFiles に直接追加しただけのファイルは処理されません。付属の MSBuild ターゲットがドキュメントとメタデータをジェネレーターへ受け渡せるよう、OpenApiWeaverDocument を使用してください。

詳しくは 設定 を参照してください。

3. 生成されたクライアントを使う

プロジェクトがビルドされると、生成された型はすべて IntelliSense 付きで利用可能になります。

// コンストラクター引数は security scheme から生成されます
var client = new PetstoreClient(accessToken: "your-token");

// 操作は OpenAPI tag ごとにグループ化されます
var pet = await client.Pets.GetAsync(petId: 1);

生成されたクライアントは、最初の OpenAPI servers エントリをもとに BaseAddress を設定した内部 HttpClient を作成します。すべてのメソッドは async で、任意の CancellationToken を受け取れます。

ルートクライアントクラスは IDisposable を実装しており、使用後に Dispose() を呼び出すことで内部の HttpClient を解放できます。また partial class として生成されるため、別ファイルで追加のメソッドを定義して拡張できます。

生成パイプラインや内部構造の詳細は 仕組み を参照してください。