注意
這不是這篇文章的最新版本。 關於目前版本，請參閱 本文的 .NET 10 版本。
警告
不再支援此版本的 ASP.NET Core。 如需詳細資訊，請參閱 .NET 和 .NET Core 支持原則。 如需目前的版本，請參閱 本文的 .NET 9 版本。
OpenAPI (Swagger) 是用來描述 REST API 的語言無關規格。 gRPC JSON 轉碼支援從已轉碼的 RESTful API 產生 OpenAPI。
Microsoft.AspNetCore.Grpc.Swagger 封裝：
- 整合 gRPC JSON 轉碼與 Swashbuckle。
- 在 .NET 7 中為實驗性質，可讓我們探索提供 OpenAPI 支援的最佳方式。
開始
若要使用 gRPC JSON 轉碼來啟用 OpenAPI：
- 按照 入門說明設定 gRPC JSON 轉碼。
- 將套件參考新增至
Microsoft.AspNetCore.Grpc.Swagger。 版本必須是 0.3.0-xxx 或更新版本。 - 在啟動中設定 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();
從 .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 頁面：
