Compartir a través de

Documentación de la transcodificación JSON de gRPC con Swagger/OpenAPI

  • Artículo

Nota:

Esta no es la versión más reciente de este artículo. Para la versión actual, consulta la versión .NET 8 de este artículo.

Advertencia

Esta versión de ASP.NET Core ya no se admite. Para obtener más información, consulta la Directiva de soporte técnico de .NET y .NET Core. Para la versión actual, consulta la versión .NET 8 de este artículo.

Importante

Esta información hace referencia a un producto en versión preliminar, el cual puede sufrir importantes modificaciones antes de que se publique la versión comercial. Microsoft no proporciona ninguna garantía, expresa o implícita, con respecto a la información proporcionada aquí.

Para la versión actual, consulta la versión .NET 8 de este artículo.

Por James Newton-King

OpenAPI (Swagger) es una especificación independiente del lenguaje que sirve para describir API REST. La transcodificación JSON de gRPC admite la generación de OpenAPI a partir de API RESTful transcodificadas. El paquete Microsoft.AspNetCore.Grpc.Swagger:

  • Integra la transcodificación JSON de gRPC con Swashbuckle.
  • Es experimental en .NET 7 para así permitirnos explorar la mejor manera de proporcionar compatibilidad con OpenAPI.

Introducción

Para habilitar OpenAPI con la transcodificación JSON de gRPC:

  1. Agregue una referencia de paquete a Microsoft.AspNetCore.Grpc.Swagger. La versión debe ser 0.3.0-xxx o posterior.
  2. Configure Swashbuckle en el inicio. El método AddGrpcSwagger configura Swashbuckle para incluir los puntos de conexión de 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

Para obtener instrucciones sobre cómo agregar paquetes a aplicaciones .NET, consulta los artículos de Instalación y administración de paquetes en Flujo de trabajo de consumo de paquetes (documentación de NuGet). Confirme las versiones correctas del paquete en NuGet.org.

Adición de descripciones de OpenAPI a partir de comentarios de .proto

Genere descripciones de OpenAPI a partir de comentarios en el contrato .proto, como en el ejemplo siguiente:

// 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 los comentarios de OpenAPI de gRPC:

  1. Habilite el archivo de documentación XML en el proyecto de servidor con <GenerateDocumentationFile>true</GenerateDocumentationFile>.
  2. Configure AddSwaggerGen para leer el archivo XML generado. Pase la ruta de acceso del archivo XML a IncludeXmlComments y IncludeGrpcXmlComments, como en el ejemplo siguiente:
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 Swashbuckle genera OpenAPI con comentarios para los servicios gRPC RESTful, inicia la aplicación y ve a la página de la interfaz de usuario de Swagger:

Interfaz de usuario de Swagger

Recursos adicionales