Share via

Documentation sur le transcodage gRPC JSON avec Swagger/OpenAPI

  • Article

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.

Bien démarrer

Pour activer OpenAPI avec le transcodage gRPC JSON :

  1. Ajoutez une référence de package à Microsoft.AspNetCore.Grpc.Swagger. La version doit être 0.3.0-xxx ou ultérieure.
  2. 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();

Notes

Pour obtenir des conseils sur l’ajout de packages à des applications .NET, consultez les articles figurant sous Installer et gérer des packages dans Flux de travail de la consommation des packages (documentation NuGet). Vérifiez les versions du package sur NuGet.org.

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 :

Swagger UI

Ressources supplémentaires