Swagger / OpenAPI ile gRPC JSON kodlama dönüştürme belgeleri
Uyarı
ASP.NET Core'un bu sürümü artık desteklenmiyor. Daha fazla bilgi için bkz . .NET ve .NET Core Destek İlkesi. Geçerli sürüm için bu makalenin .NET 8 sürümüne bakın.
Yayınlayan James Newton-King
OpenAPI (Swagger), API'leri açıklamaya REST yönelik dilden bağımsız bir belirtimdir. gRPC JSON transcoding, transcoded RESTful API'lerinden OpenAPI oluşturulmasını destekler. Paket Microsoft.AspNetCore.Grpc.Swagger
:
- gRPC JSON transcoding'i Swashbuckle ile tümleştirir.
- OpenAPI desteği sağlamanın en iyi yolunu keşfetmemize olanak sağlamak için .NET 7'de deneyseldir.
Kullanmaya başlayın
gRPC JSON kodlama ile OpenAPI'yi etkinleştirmek için:
- öğesine
Microsoft.AspNetCore.Grpc.Swagger
bir paket başvurusu ekleyin. Sürüm 0.3.0-xxx veya üzeri olmalıdır. - Başlangıçta Swashbuckle'ı yapılandırın. yöntemi Swashbuckle'ı
AddGrpcSwagger
gRPC uç noktalarını içerecek şekilde yapılandırıyor.
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();
Not
.NET uygulamalarına paket ekleme hakkında yönergeler için, Paket tüketimi iş akışında (NuGet belgeleri) paketleri yüklemek ve yönetmek altındaki makalelere bakın. NuGet.org'da doğru paket sürümlerini onaylayın.
Açıklamalardan .proto
OpenAPI açıklamaları ekleme
Aşağıdaki örnekte olduğu gibi sözleşmedeki .proto
açıklamalardan OpenAPI açıklamaları oluşturun:
// 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 açıklamalarını etkinleştirmek için:
- ile
<GenerateDocumentationFile>true</GenerateDocumentationFile>
sunucu projesinde XML belge dosyasını etkinleştirin. - Oluşturulan XML dosyasını okuyacak şekilde yapılandırın
AddSwaggerGen
. Xml dosya yolunuIncludeXmlComments
aşağıdaki örnekte olduğu gibi veIncludeGrpcXmlComments
öğesine geçirin:
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'ın ful gRPC hizmetlerinin RESTaçıklamalarıyla OpenAPI oluşturduğunu onaylamak için uygulamayı başlatın ve Swagger KULLANıCı Arabirimi sayfasına gidin:
Ek kaynaklar
ASP.NET Core