Dokumentation zur gRPC JSON-Transcodierung mit Swagger/OpenAPI
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
- Fügen Sie
Microsoft.AspNetCore.Grpc.Swagger
einen Paketverweis hinzu. Als Version muss 0.3.0-xxx oder höher verwendet werden. - 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
- Aktivieren Sie die XML-Dokumentationsdatei im Serverprojekt mit
<GenerateDocumentationFile>true</GenerateDocumentationFile>
. - Konfigurieren Sie
AddSwaggerGen
so, dass die generierte XML-Datei gelesen wird. Übergeben Sie den XML-Dateipfad anIncludeXmlComments
undIncludeGrpcXmlComments
, 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:
Zusätzliche Ressourcen
Feedback
https://aka.ms/ContentUserFeedback.
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unterFeedback senden und anzeigen für