具有 Swagger/OpenAPI 的 gRPC JSON 轉碼文件

  • 發行項

作者：James Newton-King

OpenAPI (Swagger) 是用來描述 REST API 的語言無關規格。 gRPC JSON 轉碼支援從已轉碼的 RESTful API 產生 OpenAPI。 Microsoft.AspNetCore.Grpc.Swagger 封裝：

  • 整合 gRPC JSON 轉碼與 Swashbuckle。
  • 在 .NET 7 中為實驗性質，可讓我們探索提供 OpenAPI 支援的最佳方式。

開始使用

若要使用 gRPC JSON 轉碼來啟用 OpenAPI：

  1. 將套件參考新增至 Microsoft.AspNetCore.Grpc.Swagger。 版本必須是 0.3.0-xxx 或更新版本。
  2. 在啟動中設定 Swashbuckle。 AddGrpcSwagger 方法會設定 Swashbuckle 以包括 gRPC 端點。
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();

注意

如需將套件新增至 .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

其他資源