Bagikan melalui

Dokumentasi transcoding JSON gRPC dengan Swagger / OpenAPI

  • Artikel

Catatan

Ini bukan versi terbaru dari artikel ini. Untuk rilis saat ini, lihat versi .NET 8 dari artikel ini.

Peringatan

Versi ASP.NET Core ini tidak lagi didukung. Untuk informasi selengkapnya, lihat Kebijakan Dukungan .NET dan .NET Core. Untuk rilis saat ini, lihat versi .NET 8 dari artikel ini.

Penting

Informasi ini berkaitan dengan produk pra-rilis yang mungkin dimodifikasi secara substansial sebelum dirilis secara komersial. Microsoft tidak memberikan jaminan, tersirat maupun tersurat, sehubungan dengan informasi yang diberikan di sini.

Untuk rilis saat ini, lihat versi .NET 8 dari artikel ini.

Oleh James Newton-King

OpenAPI (Swagger) adalah spesifikasi agnostik bahasa untuk menjelaskan REST API. Transcoding JSON gRPC mendukung pembuatan OpenAPI dari API RESTful yang ditranskodekan. Paket Microsoft.AspNetCore.Grpc.Swagger :

  • Mengintegrasikan transcoding GRPC JSON dengan Swashbuckle.
  • Bersifat eksperimental di .NET 7 untuk memungkinkan kami menjelajahi cara terbaik untuk memberikan dukungan OpenAPI.

Memulai

Untuk mengaktifkan OpenAPI dengan transcoding JSON gRPC:

  1. Tambahkan referensi paket ke Microsoft.AspNetCore.Grpc.Swagger. Versi harus 0.3.0-xxx atau yang lebih baru.
  2. Konfigurasikan Swashbuckle dalam startup. Metode ini AddGrpcSwagger mengonfigurasi Swashbuckle untuk menyertakan titik akhir 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();

Catatan

Untuk panduan tentang menambahkan paket ke aplikasi .NET, lihat artikel di bagian Menginstal dan mengelola paket di Alur kerja konsumsi paket (dokumentasi NuGet). Konfirmasikan versi paket yang benar di NuGet.org.

Menambahkan deskripsi OpenAPI dari .proto komentar

Hasilkan deskripsi OpenAPI dari komentar dalam .proto kontrak, seperti dalam contoh berikut:

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

Untuk mengaktifkan komentar gRPC OpenAPI:

  1. Aktifkan file dokumentasi XML dalam proyek server dengan <GenerateDocumentationFile>true</GenerateDocumentationFile>.
  2. Konfigurasikan AddSwaggerGen untuk membaca file XML yang dihasilkan. Teruskan jalur file XML ke IncludeXmlComments dan IncludeGrpcXmlComments, seperti dalam contoh berikut:
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);
});

Untuk mengonfirmasi bahwa Swashbuckle membuat OpenAPI dengan deskripsi untuk layanan RESTful gRPC, mulai aplikasi dan navigasikan ke halaman antarmuka pengguna Swagger:

Antarmuka Pengguna Swagger

Sumber Daya Tambahan: