Documentation sur le transcodage gRPC JSON avec Swagger/OpenAPI

Par James Newton-King

OpenAPI (Swagger) est une spécification indépendante du langage pour décrire les API REST. Le transcodage gRPC JSON prend en charge la génération d’OpenAPI à partir d’API RESTful transcodées. Package Microsoft.AspNetCore.Grpc.Swagger :

• Intègre le transcodage gRPC JSON avec Swashbuckle.
• Est expérimental dans .NET 7 pour nous permettre de trouver la meilleure façon d’offrir la prise en charge d’OpenAPI.

Démarrage

Pour activer OpenAPI avec le transcodage gRPC JSON :

1. Configurez le transcodage JSON gRPC en suivant les instructions de prise en main.
2. Ajoutez une référence de package à Microsoft.AspNetCore.Grpc.Swagger. La version doit être 0.3.0-xxx ou ultérieure.
3. Configurez Swashbuckle au démarrage. La méthode AddGrpcSwagger configure Swashbuckle pour inclure des points de terminaison 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();

Ajouter des descriptions OpenAPI à partir de commentaires .proto

Générez des descriptions OpenAPI à partir de commentaires dans le contrat .proto, comme dans l’exemple suivant :

// 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;
}

Pour activer les commentaires OpenAPI gRPC :

1. Activez le fichier de documentation XML dans le projet serveur avec <GenerateDocumentationFile>true</GenerateDocumentationFile>.
2. Configurez AddSwaggerGen pour lire le fichier XML généré. Transmettez le chemin du fichier XML à IncludeXmlComments et IncludeGrpcXmlComments, comme dans l’exemple suivant :

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);
});

Pour vérifier que Swashbuckle génère OpenAPI avec des descriptions pour les services RESTful gRPC, démarrez l’application et accédez à la page de l’interface utilisateur de Swagger :

Ressources supplémentaires

• Transcodage JSON gRPC dans les applications ASP.NET Core gRPC
• Page d’accueil OpenAPI
• Dépôt GitHub Swashbuckle.AspNetCore