Condividi tramite

Documentazione sulla transcodifica JSON gRPC con Swagger/OpenAPI

Nota

Questa non è la versione più recente di questo articolo. Per la versione corrente, vedere la versione .NET 10 di questo articolo.

Avviso

Questa versione di ASP.NET Core non è più supportata. Per altre informazioni, vedere i criteri di supporto di .NET e .NET Core. Per la versione corrente, vedere la versione .NET 9 di questo articolo.

Di James Newton-King

OpenAPI (Swagger) è una specifica indipendente dal linguaggio per la descrizione delle REST API. La transcodifica JSON gRPC supporta la generazione di OpenAPI da API RESTful transcodificate. Il pacchetto Microsoft.AspNetCore.Grpc.Swagger:

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

Operazioni preliminari

Per abilitare OpenAPI con la transcodifica JSON gRPC:

  1. Configurare la transcodifica JSON gRPC seguendo le istruzioni introduttive.
  2. Aggiungere un riferimento al pacchetto a Microsoft.AspNetCore.Grpc.Swagger. La versione deve essere 0.3.0-xxx o successiva.
  3. 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 servizi RESTful gRPC, avviare l'app e passare alla pagina dell'interfaccia utente di Swagger:

Interfaccia utente di Swagger

Risorse aggiuntive

  • Last updated on