Partilhar via

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

  • Artigo

Por James Newton-King

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

  • Integra a transcodificação 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 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 gRPC RESTful, inicie o aplicativo e navegue até a página da interface do usuário do Swagger:

Swagger UI

Recursos adicionais