Dela via

gRPC JSON-omkodningsdokumentation med Swagger/OpenAPI

Anmärkning

Det här är inte den senaste versionen av den här artikeln. Den aktuella versionen finns i .NET 10-versionen av den här artikeln.

Varning

Den här versionen av ASP.NET Core stöds inte längre. Mer information finns i supportpolicyn för .NET och .NET Core. För den nuvarande utgåvan, se .NET 9-versionen av den här artikeln .

Av James Newton-King

OpenAPI (Swagger) är en språkagnostisk specifikation för att beskriva REST API:er. gRPC JSON-omkodning stöder generering av OpenAPI från transkodade RESTful-API:er. Paketet Microsoft.AspNetCore.Grpc.Swagger :

  • Integrerar gRPC JSON-omkodning med Swashbuckle.
  • Är experimentellt i .NET 7 så att vi kan utforska det bästa sättet att tillhandahålla OpenAPI-stöd.

Get started

Så här aktiverar du OpenAPI med gRPC JSON-transkodning:

  1. Konfigurera gRPC JSON-transkodning genom att följa instruktionerna för att komma igång.
  2. Lägg till en paketreferens till Microsoft.AspNetCore.Grpc.Swagger. Versionen måste vara 0.3.0-xxx eller senare.
  3. Konfigurera Swashbuckle vid programstart. Metoden AddGrpcSwagger konfigurerar Swashbuckle för att inkludera gRPC-slutpunkter.
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();

Anmärkning

Vägledning om hur du lägger till paket i .NET-appar finns i artiklarna under Installera och hantera paket i arbetsflödet för paketförbrukning (NuGet-dokumentation). Bekräfta rätt paketversioner på NuGet.org.

Lägga till OpenAPI-beskrivningar från .proto kommentarer

Generera OpenAPI-beskrivningar från kommentarer i .proto kontraktet, som i följande exempel:

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

Så här aktiverar du gRPC OpenAPI-kommentarer:

  1. Aktivera XML-dokumentationsfilen i serverprojektet med <GenerateDocumentationFile>true</GenerateDocumentationFile>.
  2. Konfigurera AddSwaggerGen för att läsa den genererade XML-filen. Skicka XML-filsökvägen till IncludeXmlComments och IncludeGrpcXmlComments, som i följande exempel:
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);
});

Om du vill bekräfta att Swashbuckle genererar OpenAPI med beskrivningar för RESTful gRPC-tjänsterna startar du appen och går till swagger-användargränssnittssidan:

Swagger-användargränssnitt

Ytterligare resurser

  • Last updated on