Megosztás a következőn keresztül:

gRPC JSON transzkódolási dokumentáció a Swaggerrel / OpenAPI

Megjegyzés:

Ez nem a cikk legújabb verziója. Az aktuális kiadásról a cikk .NET 10-es verziójában olvashat.

Figyelmeztetés

A ASP.NET Core ezen verziója már nem támogatott. További információt a .NET és a .NET Core támogatási szabályzatában talál. A jelen cikk .NET 9-es verzióját lásd az aktuális kiadásért .

Írta: James Newton-King

Az OpenAPI (Swagger) egy nyelvspecifikus specifikáció az API-k leírásához REST . A gRPC JSON-transzkódolás támogatja az OpenAPI létrehozását a transzkódolt RESTful API-kból. A Microsoft.AspNetCore.Grpc.Swagger csomag:

  • Integrálja a gRPC JSON-átkódolást a Swashbuckle-jal.
  • Kísérletezik a .NET 7-ben, hogy felfedezzük az OpenAPI-támogatás legjobb módját.

Első lépések

Az OpenAPI engedélyezése gRPC JSON-átkódolással:

  1. A gRPC JSON-átkódolás beállítása az első lépések utasításait követve.
  2. Adj hozzá egy csomaghivatkozást a Microsoft.AspNetCore.Grpc.Swagger-hoz. A verziónak 0.3.0-xxx vagy újabbnak kell lennie.
  3. Konfigurálja a Swashbuckle-t a startupnál. A AddGrpcSwagger metódus úgy konfigurálja a Swashbuckle-t, hogy gRPC-végpontokat is tartalmazzon.
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();

Megjegyzés:

A csomagok .NET-alkalmazásokhoz való hozzáadásáról a Csomagok telepítése és kezelésea csomaghasználati munkafolyamatban (NuGet-dokumentáció) című cikkben talál útmutatást. Ellenőrizze a megfelelő csomagverziókat a NuGet.org.

OpenAPI-leírások hozzáadása megjegyzésekből .proto

OpenAPI-leírások létrehozása a .proto szerződés megjegyzéseiből, az alábbi példához hasonlóan:

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

A gRPC OpenAPI-megjegyzések engedélyezése:

  1. Engedélyezze az XML-dokumentációs fájlt a kiszolgálóprojektben a következővel <GenerateDocumentationFile>true</GenerateDocumentationFile>: .
  2. Konfigurálja AddSwaggerGen a létrehozott XML-fájl olvasására. Adja át az XML-fájl elérési útját IncludeXmlComments és IncludeGrpcXmlComments a következő példához hasonlóan:
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);
});

Annak ellenőrzéséhez, hogy a Swashbuckle openAPI-t hoz-e létre a RESTful gRPC-szolgáltatások leírásával, indítsa el az alkalmazást, és lépjen a Swagger felhasználói felületére:

Swagger felhasználói felület

További erőforrások

  • Last updated on