Condividi tramite

Documentazione sulla transcodifica di gRPC JSON con Swagger/OpenAPI

  • Articolo

Di James Newton-King

OpenAPI (Swagger) è una specifica indipendente dal linguaggio per la descrizione delle REST API. la transcodifica gRPC JSON supporta la generazione di OpenAPI da API con codifica transcodificata REST. Pacchetto Microsoft.AspNetCore.Grpc.Swagger :

  • Integra la transcodifica gRPC JSON con Swashbuckle.
  • È sperimentale in .NET 7 per consentire di esplorare il modo migliore per fornire il supporto OpenAPI.

Introduzione

Per abilitare OpenAPI con transcodifica gRPC JSON:

  1. Aggiungere un riferimento al pacchetto a Microsoft.AspNetCore.Grpc.Swagger. La versione deve essere 0.3.0-xxx o successiva.
  2. Configurare Swashbuckle all'avvio. Il AddGrpcSwagger metodo configura Swashbuckle per includere gli endpoint 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();

Nota

Per indicazioni sull'aggiunta di pacchetti alle app .NET, vedere gli articoli sotto Installare e gestire pacchetti in Flusso di lavoro dell'utilizzo di pacchetti (documentazione di NuGet). Confermare le versioni corrette del pacchetto all'indirizzo NuGet.org.

Aggiungere descrizioni OpenAPI dai .proto commenti

Generare descrizioni OpenAPI dai commenti nel .proto contratto, come nell'esempio seguente:

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

Per abilitare i commenti OpenAPI gRPC:

  1. Abilitare il file di documentazione XML nel progetto server con <GenerateDocumentationFile>true</GenerateDocumentationFile>.
  2. Configurare AddSwaggerGen per leggere il file XML generato. Passare il percorso del file XML a IncludeXmlComments e IncludeGrpcXmlComments, come nell'esempio seguente:
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);
});

Per verificare che Swashbuckle generi OpenAPI con descrizioni per i RESTservizi gRPC ful, avviare l'app e passare alla pagina dell'interfaccia utente di Swagger:

Swagger UI

Risorse aggiuntive