Teilen über

Dokumentation zur gRPC JSON-Transcodierung mit Swagger/OpenAPI

  • Artikel

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:

  • Es integriert die gRPC-JSON-Transcodierung in 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

Einen Leitfaden zum Hinzufügen von Paketen zu .NET-Apps finden Sie in Installieren und Verwalten von Paketen unter Workflow der Nutzung von Paketen (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 UI

Zusätzliche Ressourcen