Dokumentace k transkódování json gRPC s využitím Swaggeru / OpenAPI
Poznámka:
Toto není nejnovější verze tohoto článku. Aktuální verzi najdete v tomto článku ve verzi .NET 9.
Upozorňující
Tato verze ASP.NET Core se už nepodporuje. Další informace najdete v zásadách podpory .NET a .NET Core. Aktuální verzi najdete v tomto článku ve verzi .NET 9.
Důležité
Tyto informace se týkají předběžného vydání produktu, který může být podstatně změněn před komerčním vydáním. Microsoft neposkytuje žádné záruky, výslovné ani předpokládané, týkající se zde uváděných informací.
Aktuální verzi najdete v tomto článku ve verzi .NET 9.
Autor: James Newton-King
OpenAPI (Swagger) je specifikace nezávislá na jazyce pro popis REST rozhraní API. Transkódování json gRPC podporuje generování OpenAPI z transkódovaných rozhraní RESTful API. Balíček Microsoft.AspNetCore.Grpc.Swagger
:
- Integruje transkódování gRPC JSON s Swashbuckle.
- Je experimentální v .NET 7, abychom mohli prozkoumat nejlepší způsob, jak poskytnout podporu OpenAPI.
Začínáme
Povolení transkódování OpenAPI s gRPC JSON:
- Přidejte odkaz na balíček .
Microsoft.AspNetCore.Grpc.Swagger
Verze musí být 0.3.0-xxx nebo novější. - Nakonfigurujte Swashbuckle při spuštění. Metoda
AddGrpcSwagger
nakonfiguruje Swashbuckle tak, aby zahrnovala koncové body 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();
Poznámka:
Pokyny k přidávání balíčků do aplikací .NET najdete v článcích v části Instalace a správa balíčků na webu Pracovní postup používání balíčků (dokumentace k NuGetu). Ověřte správné verze balíčků na NuGet.org.
Přidání popisů OpenAPI z .proto
komentářů
Vygenerujte popisy OpenAPI z komentářů ve smlouvě .proto
, jak je znázorněno v následujícím příkladu:
// 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;
}
Povolení komentářů gRPC OpenAPI:
- Povolte soubor dokumentace XML v projektu serveru pomocí
<GenerateDocumentationFile>true</GenerateDocumentationFile>
. - Nakonfigurujte
AddSwaggerGen
čtení vygenerovaného souboru XML. Předejte cestu kIncludeXmlComments
souboru XML aIncludeGrpcXmlComments
, jako v následujícím příkladu:
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);
});
Pokud chcete ověřit, že Swashbuckle generuje OpenAPI s popisy služeb RESTful gRPC, spusťte aplikaci a přejděte na stránku Swagger UI: