Swagger / OpenAPI を使用した gRPC JSON コード変換のドキュメント
Note
これは、この記事の最新バージョンではありません。 現在のリリースについては、この記事の .NET 8 バージョンを参照してください。
警告
このバージョンの ASP.NET Core はサポート対象から除外されました。 詳細については、「.NET および .NET Core サポート ポリシー」を参照してください。 現在のリリースについては、この記事の .NET 8 バージョンを参照してください。
重要
この情報はリリース前の製品に関する事項であり、正式版がリリースされるまでに大幅に変更される可能性があります。 Microsoft はここに示されている情報について、明示か黙示かを問わず、一切保証しません。
現在のリリースについては、この記事の .NET 8 バージョンを参照してください。
作成者: James Newton-King
OpenAPI (Swagger) は REST API を記述するための仕様であり、言語に依存しません。 gRPC JSON コード変換では、トランスコードされた RESTful API からの OpenAPI の生成がサポートされています。 Microsoft.AspNetCore.Grpc.Swagger パッケージ:
- gRPC JSON コード変換を Swashbuckle と統合します。
- OpenAPI のサポートを提供する最善の方法を探ることができるように、.NET 7 の実験的機能となっています。
作業の開始
gRPC JSON コード変換での OpenAPI を有効にするには:
Microsoft.AspNetCore.Grpc.Swaggerへのパッケージ参照を追加します。 バージョンは 0.3.0-xxx 以降である必要があります。- 起動時に Swashbuckle を構成します。
AddGrpcSwaggerメソッドにより、gRPC エンドポイントを含めるように Swashbuckle が構成されます。
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddGrpc().AddJsonTranscoding();
builder.Services.AddGrpcSwagger();
builder.Services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1",
new OpenApiInfo { Title = "gRPC transcoding", Version = "v1" });
});
var app = builder.Build();
app.UseSwagger();
if (app.Environment.IsDevelopment())
{
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
});
}
app.MapGrpcService<GreeterService>();
app.Run();
Note
.NET アプリへのパッケージの追加に関するガイダンスについては、「パッケージ利用のワークフロー」 (NuGet ドキュメント) の "パッケージのインストールと管理" に関する記事を参照してください。 NuGet.org で正しいパッケージ バージョンを確認します。
.proto コメントから OpenAPI の説明を追加する
次の例のようにして、.proto コントラクト内のコメントから OpenAPI の説明を生成します。
// My amazing greeter service.
service Greeter {
// Sends a greeting.
rpc SayHello (HelloRequest) returns (HelloReply) {
option (google.api.http) = {
get: "/v1/greeter/{name}"
};
}
}
message HelloRequest {
// Name to say hello to.
string name = 1;
}
message HelloReply {
// Hello reply message.
string message = 1;
}
gRPC OpenAPI のコメントを有効にするには:
<GenerateDocumentationFile>true</GenerateDocumentationFile>を使用して、サーバー プロジェクトの XML ドキュメント ファイルを有効にします。AddSwaggerGenを構成して、生成された XML ファイルを読み取ります。 次の例のようにして、XML ファイル パスをIncludeXmlCommentsおよびIncludeGrpcXmlCommentsに渡します。
builder.Services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1",
new OpenApiInfo { Title = "gRPC transcoding", Version = "v1" });
var filePath = Path.Combine(System.AppContext.BaseDirectory, "Server.xml");
c.IncludeXmlComments(filePath);
c.IncludeGrpcXmlComments(filePath, includeControllerXmlComments: true);
});
Swashbuckle によって RESTful gRPC サービスの説明を含む OpenAPI が生成されることを確認するには、アプリを起動して Swagger UI ページに移動します。
その他のリソース
ASP.NET Core