Documentazione sulla transcodifica JSON gRPC con Swagger/OpenAPI

  • Articolo

Nota

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

Avviso

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

Importante

Queste informazioni si riferiscono a un prodotto non definitive che può essere modificato in modo sostanziale prima che venga rilasciato commercialmente. Microsoft non riconosce alcuna garanzia, espressa o implicita, in merito alle informazioni qui fornite.

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. 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 servizi RESTful gRPC, avviare l'app e passare alla pagina dell'interfaccia utente di Swagger:

Interfaccia utente di Swagger

Risorse aggiuntive