Documentação de transcodificação do gRPC JSON com Swagger/OpenAPI
Observação
Esta não é a versão mais recente deste artigo. Para informações sobre a versão vigente, confira a Versão do .NET 8 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 informações sobre a versão vigente, confira a Versão do .NET 8 deste artigo.
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:
- Adicione uma referência de pacote para
Microsoft.AspNetCore.Grpc.Swagger
. A versão deve ser 0.3.0-xxx ou posterior. - 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:
- Habilite o arquivo de documentação XML no projeto do servidor com
<GenerateDocumentationFile>true</GenerateDocumentationFile>
. - Configure
AddSwaggerGen
para ler o arquivo XML gerado. Passe o caminho do arquivo XML paraIncludeXmlComments
eIncludeGrpcXmlComments
, 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: