Swagger / OpenAPI を使用した gRPC JSON コード変換のドキュメント

作成者: 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 を有効にするには:

1. Microsoft.AspNetCore.Grpc.Swagger へのパッケージ参照を追加します。 バージョンは 0.3.0-xxx 以降である必要があります。
2. 起動時に 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();
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 のコメントを有効にするには:

1. <GenerateDocumentationFile>true</GenerateDocumentationFile> を使用して、サーバー プロジェクトの XML ドキュメント ファイルを有効にします。
2. 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 gRPC アプリでの gRPC JSON コード変換
• OpenAPI のホームページ
• Swashbuckle.AspNetCore GitHub リポジトリ