Sử dụng OpenAPI với gRPC JSON transcoding trong ASP.NET Core

Nguồn: Use OpenAPI with gRPC JSON transcoding ASP.NET Core apps

OpenAPI (Swagger) là một đặc tả (specification) độc lập với ngôn ngữ dùng để mô tả REST API. gRPC JSON transcoding (chuyển mã JSON) hỗ trợ tạo OpenAPI từ các RESTful API đã được chuyển mã. Gói Microsoft.AspNetCore.Grpc.Swagger:

Tích hợp gRPC JSON transcoding với Swashbuckle.
Là tính năng thử nghiệm (experimental) trong .NET 7 để khám phá cách tốt nhất hỗ trợ OpenAPI.

Bắt đầu

Để bật OpenAPI với gRPC JSON transcoding:

Cài đặt gRPC JSON transcoding theo hướng dẫn bắt đầu.
Thêm tham chiếu gói (package reference) tới Microsoft.AspNetCore.Grpc.Swagger. Phiên bản phải là 0.3.0-xxx trở lên.
Cấu hình Swashbuckle khi khởi động. Phương thức AddGrpcSwagger cấu hình Swashbuckle để bao gồm các endpoint gRPC.

csharp

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();

Lưu ý: Để biết hướng dẫn thêm gói vào ứng dụng .NET, xem các bài viết trong phần Install and manage packages tại Package consumption workflow (NuGet documentation). Xác nhận phiên bản gói chính xác tại NuGet.org.

Thêm mô tả OpenAPI từ chú thích `.proto`

Tạo mô tả OpenAPI từ các chú thích trong hợp đồng .proto (tệp định nghĩa giao thức), như ví dụ sau:

protobuf

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

Để bật chú thích OpenAPI cho gRPC:

Bật tệp tài liệu XML (XML documentation file) trong dự án server với <GenerateDocumentationFile>true</GenerateDocumentationFile>.
Cấu hình AddSwaggerGen để đọc tệp XML được tạo ra. Truyền đường dẫn tệp XML vào IncludeXmlComments và IncludeGrpcXmlComments, như ví dụ sau:

csharp

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

Để xác nhận rằng Swashbuckle đang tạo OpenAPI với các mô tả cho các dịch vụ gRPC RESTful, hãy khởi động ứng dụng và điều hướng đến trang Swagger UI.

Sử dụng OpenAPI với gRPC JSON transcoding trong ASP.NET Core

Bắt đầu

Thêm mô tả OpenAPI từ chú thích .proto

Thêm mô tả OpenAPI từ chú thích `.proto`