Udostępnij za pośrednictwem

Dokumentacja transkodowania gRPC JSON za pomocą struktury Swagger/OpenAPI

Uwaga

Nie jest to najnowsza wersja tego artykułu. Aby zapoznać się z bieżącą wersją, zobacz wersję tego artykułu platformy .NET 9.

Ostrzeżenie

Ta wersja ASP.NET Core nie jest już obsługiwana. Aby uzyskać więcej informacji, zobacz zasady pomocy technicznej platformy .NET i platformy .NET Core. Aby zapoznać się z bieżącą wersją, zobacz wersję tego artykułu platformy .NET 9.

Ważne

Te informacje odnoszą się do produktu w wersji wstępnej, który może zostać znacząco zmodyfikowany, zanim zostanie wydany komercyjnie. Firma Microsoft nie udziela żadnych gwarancji, jawnych lub domniemanych, w odniesieniu do informacji podanych w tym miejscu.

Aby zapoznać się z bieżącą wersją, zobacz wersję tego artykułu platformy .NET 9.

Autor: James Newton-King

OpenAPI (Swagger) to niezależna od języka specyfikacja do opisywania REST interfejsów API. Transkodowanie gRPC JSON obsługuje generowanie interfejsu OpenAPI z transkodowanych interfejsów API RESTful. Pakiet Microsoft.AspNetCore.Grpc.Swagger :

  • Integruje transkodowanie gRPC JSON z pakietem Swashbuckle.
  • Jest eksperymentalny na platformie .NET 7, aby umożliwić nam zapoznanie się z najlepszym sposobem zapewnienia obsługi interfejsu OpenAPI.

Rozpocznij

Aby włączyć interfejs OpenAPI z transkodowaniem JSON gRPC:

  1. Dodaj odwołanie do pakietu do Microsoft.AspNetCore.Grpc.Swagger. Wersja musi być 0.3.0-xxx lub nowsza.
  2. Skonfiguruj pakiet Swashbuckle podczas uruchamiania. Metoda AddGrpcSwagger konfiguruje pakiet Swashbuckle tak, aby zawierał punkty końcowe 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();

Uwaga

Aby uzyskać instrukcje dodawania pakietów do aplikacji .NET, zobacz artykuły w sekcji Instalowanie pakietów i zarządzanie nimi w temacie Przepływ pracy użycia pakietów (dokumentacja programu NuGet). Sprawdź prawidłowe wersje pakietów pod adresem NuGet.org.

Dodawanie opisów interfejsu OpenAPI z .proto komentarzy

Wygeneruj opisy interfejsu OpenAPI na podstawie komentarzy w umowie .proto , jak w poniższym przykładzie:

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

Aby włączyć komentarze gRPC OpenAPI:

  1. Włącz plik dokumentacji XML w projekcie serwera za pomocą polecenia <GenerateDocumentationFile>true</GenerateDocumentationFile>.
  2. Skonfiguruj AddSwaggerGen , aby odczytać wygenerowany plik XML. Przekaż ścieżkę pliku XML do IncludeXmlComments i IncludeGrpcXmlComments, jak pokazano w poniższym przykładzie:
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);
});

Aby potwierdzić, że pakiet Swashbuckle generuje interfejs OpenAPI z opisami dla usług GRPC RESTful, uruchom aplikację i przejdź do strony interfejsu użytkownika struktury Swagger:

Interfejs użytkownika struktury Swagger

Dodatkowe zasoby