Partilhar via

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

  • Artigo

Observação

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

Aviso

Esta versão do ASP.NET Core não tem mais suporte. Para obter mais informações, confira .NET e a Política de Suporte do .NET Core. Para informações sobre a versão vigente, confira a Versão do .NET 8 deste artigo.

Importante

Essas informações relacionam-se ao produto de pré-lançamento, que poderá ser substancialmente modificado antes do lançamento comercial. A Microsoft não oferece nenhuma garantia, explícita ou implícita, quanto às informações fornecidas aqui.

Para a versão atual, consulte a versão .NET 9 deste artigo.

Por James Newton-King

O Swagger (OpenAPI) é uma especificação independente de linguagem para descrever APIs REST. A transcodificação de gRPC JSON dá suporte à geração de OpenAPI a partir de APIs RESTful transcodificadas. O pacote Microsoft.AspNetCore.Grpc.Swagger:

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

Introdução

Para habilitar o OpenAPI com transcodificação de gRPC JSON:

  1. Adicione uma referência de pacote para Microsoft.AspNetCore.Grpc.Swagger. A versão deve ser 0.3.0-xxx ou posterior.
  2. Configurar o Swashbuckle na inicialização. O método AddGrpcSwagger configura o Swashbuckle para incluir pontos de extremidade 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();

Observação

Para obter diretrizes sobre como adicionar pacotes a aplicativos .NET, consulte os artigos em Instalar e gerenciar pacotes no Fluxo de trabalho de consumo de pacotes (documentação do NuGet). Confirme as versões corretas de pacote em NuGet.org.

Adicionar descrições de OpenAPI de comentários .proto

Gere descrições de OpenAPI de comentários no contrato .proto, como no exemplo a seguir:

// 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 habilitar comentários do gRPC OpenAPI:

  1. Habilite o arquivo de documentação XML no projeto do servidor com <GenerateDocumentationFile>true</GenerateDocumentationFile>.
  2. Configure AddSwaggerGen para ler o arquivo XML gerado. Passe o caminho do arquivo XML para IncludeXmlComments e IncludeGrpcXmlComments, como no exemplo a seguir:
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 se o Swashbuckle está gerando OpenAPI com descrições para os serviços de gRPC RESTful, inicie o aplicativo e navegue até a página da interface do usuário do Swagger:

Interface do usuário do Swagger

Recursos adicionais