Compartir a través de

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

  • 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 gRPC JSON 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 gRPC JSON:

  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, consulte los artículos de Instalación y administración de paquetes en Flujo de trabajo de consumo de paquetes (NuGet documentación). 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, inicie la aplicación y vaya a la página de la interfaz de usuario de Swagger:

Swagger UI

Recursos adicionales