Číst v angličtině

Sdílet prostřednictvím

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

  • Článek

Poznámka

Toto není nejnovější verze tohoto článku. Aktuální verzi najdete v tomto článku ve verzi .NET 9.

Upozornění

Tato verze ASP.NET Core se už nepodporuje. Další informace najdete v zásadách podpory .NET a .NET Core. Aktuální verzi najdete v tomto článku ve verzi .NET 9.

Důležité

Tyto informace se týkají předběžného vydání produktu, který může být podstatně změněn před komerčním vydáním. Microsoft neposkytuje žádné záruky, výslovné ani předpokládané, týkající se zde uváděných informací.

Aktuální verzi najdete v tomto článku ve verzi .NET 9.

Autor: James Newton-King

OpenAPI (Swagger) je specifikace nezávislá na jazyce pro popis REST rozhraní API. Transkódování json gRPC podporuje generování OpenAPI z transkódovaných rozhraní RESTful 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í transkódování OpenAPI s 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.
C# 
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:

ProtoBuf 
// 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:
C# 
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 služeb RESTful gRPC, spusťte aplikaci a přejděte na stránku Swagger UI:

Swagger UI

Další materiály