Sdílet prostřednictvím

Dokumentace k transkódování gRPC JSON s využitím Swaggeru / OpenAPI

  • Článek

Autor: James Newton-King

OpenAPI (Swagger) je specifikace nezávislá na jazyce pro popis REST rozhraní API. Transkódování gRPC JSON podporuje generování OpenAPI z transkódovaných RESTrozhraní API. Balíček Microsoft.AspNetCore.Grpc.Swagger :

  • Integruje transkódování gRPC JSON s Swashbuckle.
  • Je experimentální v .NET 7, abychom mohli prozkoumat nejlepší způsob, jak poskytnout podporu OpenAPI.

Začínáme

Povolení OpenAPI s transkódováním gRPC JSON:

  1. Přidejte odkaz na balíček .Microsoft.AspNetCore.Grpc.Swagger Verze musí být 0.3.0-xxx nebo novější.
  2. Nakonfigurujte Swashbuckle při spuštění. Metoda AddGrpcSwagger nakonfiguruje Swashbuckle tak, aby zahrnovala koncové body 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();

Poznámka

Pokyny k přidávání balíčků do aplikací .NET najdete v článcích v části Instalace a správa balíčků na webu Pracovní postup používání balíčků (dokumentace k NuGetu). Ověřte správné verze balíčků na NuGet.org.

Přidání popisů OpenAPI z .proto komentářů

Vygenerujte popisy OpenAPI z komentářů ve smlouvě .proto , jak je znázorněno v následujícím příkladu:

// 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;
}

Povolení komentářů gRPC OpenAPI:

  1. Povolte soubor dokumentace XML v projektu serveru pomocí <GenerateDocumentationFile>true</GenerateDocumentationFile>.
  2. Nakonfigurujte AddSwaggerGen čtení vygenerovaného souboru XML. Předejte cestu k IncludeXmlComments souboru XML a IncludeGrpcXmlComments, jako v následujícím příkladu:
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);
});

Pokud chcete ověřit, že Swashbuckle generuje OpenAPI s popisy pro RESTslužby ful gRPC, spusťte aplikaci a přejděte na stránku Swagger UI:

Swagger UI

Další prostředky