Partilhar via

Documentação de transcodificação JSON gRPC com Swagger / OpenAPI

Observação

Esta não é a versão mais recente deste artigo. Para a versão atual, consulte a versão .NET 10 deste artigo.

Advertência

Esta versão do ASP.NET Core não é mais suportada. Para obter mais informações, consulte a Política de suporte do .NET e do .NET Core. Para a versão atual, consulte a versão .NET 9 deste artigo.

Por James Newton-King

OpenAPI (Swagger) é uma especificação independente da linguagem para descrever REST APIs. A transcodificação de JSON do gRPC suporta gerar OpenAPI a partir das APIs RESTful transcodificadas. O pacote Microsoft.AspNetCore.Grpc.Swagger:

  • integra transcodificação JSON gRPC com Swashbuckle.
  • É experimental no .NET 7 para nos permitir explorar a melhor forma de fornecer suporte a OpenAPI.

Introdução

Para ativar OpenAPI com transcodificação JSON gRPC:

  1. Configura a transcodificação JSON gRPC seguindo as instruções de início.
  2. Adicione uma referência de pacote a Microsoft.AspNetCore.Grpc.Swagger. A versão deve ser 0.3.0-xxx ou posterior.
  3. Configurar o Swashbuckle no arranque. O método AddGrpcSwagger configura Swashbuckle para incluir gRPC endpoints.
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();

Observação

Para obter orientação sobre como adicionar pacotes a aplicativos .NET, consulte os artigos na seção Instalar e gerenciar pacotes em Workflow de utilização de pacotes (documentação do NuGet). Confirme as versões corretas do pacote em NuGet.org.

Adicionar descrições do OpenAPI a partir dos .proto comentários

Gerar descrições OpenAPI a partir dos comentários no .proto contrato, como no seguinte exemplo:

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

Para ativar comentários OpenAPI do gRPC:

  1. Ative o ficheiro de documentação XML no projeto servidor com <GenerateDocumentationFile>true</GenerateDocumentationFile>.
  2. Configure AddSwaggerGen para ler o ficheiro XML gerado. Passe o caminho do ficheiro XML para IncludeXmlComments e IncludeGrpcXmlComments, como no seguinte exemplo:
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);
});

Para confirmar que o Swashbuckle está a gerar OpenAPI com descrições dos serviços gRPC RESTful, inicie a aplicação e navegue até à página da interface do Swagger:

Swagger UI

Recursos adicionais

  • Last updated on