Aracılığıyla paylaş

Swagger / OpenAPI ile gRPC JSON kodlama dönüştürme belgeleri

  • Makale

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.

Başlarken

gRPC JSON kodlama ile OpenAPI'yi etkinleştirmek için:

  1. öğesine Microsoft.AspNetCore.Grpc.Swaggerbir paket başvurusu ekleyin. Sürüm 0.3.0-xxx veya üzeri olmalıdır.
  2. 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();

Dekont

.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:

  1. ile <GenerateDocumentationFile>true</GenerateDocumentationFile>sunucu projesinde XML belge dosyasını etkinleştirin.
  2. Oluşturulan XML dosyasını okuyacak şekilde yapılandırın AddSwaggerGen . Xml dosya yolunu IncludeXmlComments aşağıdaki örnekte olduğu gibi ve IncludeGrpcXmlCommentsöğ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:

Swagger UI

Ek kaynaklar