Partager via

Documentation sur le transcodage gRPC JSON avec Swagger/OpenAPI

  • Article

Remarque

Ceci n’est pas la dernière version de cet article. Pour la version actuelle, consultez la version .NET 9 de cet article.

Avertissement

Cette version d’ASP.NET Core n’est plus prise en charge. Pour plus d’informations, consultez la Stratégie de prise en charge de .NET et .NET Core. Pour la version actuelle, consultez la version .NET 8 de cet article.

Important

Ces informations portent sur la préversion du produit, qui est susceptible d’être en grande partie modifié avant sa commercialisation. Microsoft n’offre aucune garantie, expresse ou implicite, concernant les informations fournies ici.

Pour la version actuelle, consultez la version .NET 9 de cet 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.

Démarrage

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 :

Interface utilisateur de Swagger

Ressources supplémentaires