Freigeben über

Dokumentation zur gRPC JSON-Transcodierung mit Swagger/OpenAPI

  • Artikel

Hinweis

Dies ist nicht die neueste Version dieses Artikels. Die aktuelle Version finden Sie in der .NET 9-Version dieses Artikels.

Warnung

Diese Version von ASP.NET Core wird nicht mehr unterstützt. Weitere Informationen finden Sie in der .NET- und .NET Core-Supportrichtlinie. Die aktuelle Version finden Sie in der .NET 9-Version dieses Artikels.

Wichtig

Diese Informationen beziehen sich auf ein Vorabversionsprodukt, das vor der kommerziellen Freigabe möglicherweise noch wesentlichen Änderungen unterliegt. Microsoft gibt keine Garantie, weder ausdrücklich noch impliziert, hinsichtlich der hier bereitgestellten Informationen.

Die aktuelle Version finden Sie in der .NET 9-Version dieses Artikels.

Von James Newton-King

Bei Swagger (OpenAPI) handelt es sich um eine sprachunabhängige Spezifikation zum Beschreiben von REST-APIs. gRPC JSON-Transcodierung unterstützt das Generieren von OpenAPI aus transcodierten RESTful-APIs. Das Microsoft.AspNetCore.Grpc.Swagger-Paket:

  • Integriert die gRPC-JSON-Transcodierung mit Swashbuckle.
  • Es ist experimentell in .NET 7 enthalten, damit wir die beste Möglichkeit zur Bereitstellung von OpenAPI-Support erkunden können.

Erste Schritte

So aktivieren Sie OpenAPI mit gRPC-JSON-Transcodierung:

  1. Fügen Sie Microsoft.AspNetCore.Grpc.Swagger einen Paketverweis hinzu. Als Version muss 0.3.0-xxx oder höher verwendet werden.
  2. Konfigurieren Sie Swashbuckle in „startup“. Die AddGrpcSwagger-Methode konfiguriert Swashbuckle so, dass gRPC-Endpunkte eingeschlossen werden.
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();

Hinweis

Eine Anleitung zum Hinzufügen von Paketen zu .NET-Anwendungen finden Sie in den Artikeln unter Pakete installieren und verwalten unter Workflow für die Paketnutzung (NuGet-Dokumentation). Überprüfen Sie unter NuGet.org, ob die richtige Paketversion verwendet wird.

Hinzufügen von OpenAPI-Beschreibungen aus .proto-Kommentaren

Generieren Sie OpenAPI-Beschreibungen aus Kommentaren im .proto-Vertrag, wie im folgenden Beispiel:

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

So aktivieren Sie gRPC-OpenAPI-Kommentare

  1. Aktivieren Sie die XML-Dokumentationsdatei im Serverprojekt mit <GenerateDocumentationFile>true</GenerateDocumentationFile>.
  2. Konfigurieren Sie AddSwaggerGen so, dass die generierte XML-Datei gelesen wird. Übergeben Sie den XML-Dateipfad an IncludeXmlComments und IncludeGrpcXmlComments, wie im folgenden Beispiel gezeigt:
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);
});

Um zu überprüfen, ob Swashbuckle die OpenAPI mit Kommentaren für die RESTful-gRPC-Dienste generiert, starten Sie die App, und navigieren Sie zur Seite der Swagger-Benutzeroberfläche:

Swagger-Benutzeroberfläche

Zusätzliche Ressourcen