带有 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();
if (app.Environment.IsDevelopment())
    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

其他资源