Delen via

gRPC JSON-transcoderingsdocumentatie met Swagger/OpenAPI

Opmerking

Dit is niet de nieuwste versie van dit artikel. Zie de .NET 10-versie van dit artikel voor de huidige release.

Waarschuwing

Deze versie van ASP.NET Core wordt niet meer ondersteund. Zie het .NET- en .NET Core-ondersteuningsbeleid voor meer informatie. Zie de .NET 10-versie van dit artikel voor de huidige release.

Door James Newton-King

OpenAPI (Swagger) is een taalagnostische specificatie voor het beschrijven van REST API's. gRPC JSON-transcodering ondersteunt het genereren van OpenAPI op basis van transcoded RESTful-API's. Het Microsoft.AspNetCore.Grpc.Swagger pakket:

  • Integreert gRPC JSON-transcodering met Swashbuckle.
  • Is experimenteel in .NET 7, zodat we de beste manier kunnen verkennen om OpenAPI-ondersteuning te bieden.

Get started

OpenAPI met gRPC JSON-transcodering inschakelen:

  1. Stel gRPC JSON-transcodering in door de instructies voor aan de slag te volgen.
  2. Voeg een pakketreferentie toe aan Microsoft.AspNetCore.Grpc.Swagger. De versie moet 0.3.0-xxx of hoger zijn.
  3. Configureer Swashbuckle bij het opstarten. De AddGrpcSwagger methode configureert Swashbuckle om gRPC-eindpunten op te nemen.
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();

Opmerking

Zie voor richtlijnen over het toevoegen van pakketten aan .NET-apps de artikelen onder Pakketten installeren en beheren in de Package consumption workflow (NuGet-documentatie). Bevestig de juiste pakketversies op NuGet.org.

OpenAPI-beschrijvingen toevoegen vanuit .proto opmerkingen

OpenAPI-beschrijvingen genereren op basis van opmerkingen in het .proto contract, zoals in het volgende voorbeeld:

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

GRPC OpenAPI-opmerkingen inschakelen:

  1. Schakel het XML-documentatiebestand in het serverproject in met <GenerateDocumentationFile>true</GenerateDocumentationFile>.
  2. Configureren AddSwaggerGen om het gegenereerde XML-bestand te lezen. Geef het XML-bestandspad door aan IncludeXmlComments en IncludeGrpcXmlComments, zoals in het volgende voorbeeld:
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);
});

Als u wilt controleren of Swashbuckle OpenAPI genereert met beschrijvingen voor de RESTful gRPC-services, start u de app en gaat u naar de pagina Swagger UI:

Swagger UI

Aanvullende bronnen

  • Last updated on