次の方法で共有


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

Note

これは、この記事の最新バージョンではありません。 現在のリリースについては、この記事の .NET 9 バージョンを参照してください。

警告

このバージョンの ASP.NET Core はサポート対象から除外されました。 詳細については、 .NET および .NET Core サポート ポリシーを参照してください。 現在のリリースについては、この記事の .NET 9 バージョンを参照してください。

重要

この情報はリリース前の製品に関する事項であり、正式版がリリースされるまでに大幅に変更される可能性があります。 Microsoft はここに示されている情報について、明示か黙示かを問わず、一切保証しません。

現在のリリースについては、この記事の .NET 9 バージョンを参照してください。

作成者: 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();
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 のコメントを有効にするには:

  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 ページに移動します。

Swagger UI

その他のリソース