ASP.NET Core: Tài liệu chuyển mã JSON gRPC với Swagger/OpenAPI

Trong bài viết này

1. Bắt đầu
2. Thêm mô tả OpenAPI từ chú thích .proto
3. Tài nguyên bổ sung

OpenAPI (Swagger) là một đặc tả ngôn ngữ bất khả tri để mô tả các API REST. Chuyển mã JSON gRPC hỗ trợ tạo OpenAPI từ các API RESTful được chuyển mã. Gói Microsoft.AspNetCore.Grpc.Swagger:

• Tích hợp chuyển mã JSON gRPC với Swashbuckle.
• Đang thử nghiệm trong .NET 7 để cho phép ta khám phá cách tốt nhất để cung cấp hỗ trợ OpenAPI.

Bắt đầu

Để bật OpenAPI bằng chuyển mã JSON gRPC:

1. Thêm tham chiếu gói vào Microsoft.AspNetCore.Grpc.Swagger. Phiên bản phải là 0.3.0-xxx trở lên.
2. Định cấu hình Swashbuckle khi khởi động. Phương thức AddGrpcSwagger sẽ định cấu hình Swashbuckle để bao gồm các điểm cuối (endpoint) 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();
app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
});
app.MapGrpcService<GreeterService>();

app.Run();

Ghi chú

Để biết hướng dẫn về cách thêm gói vào ứng dụng .NET, hãy xem các bài viết trong Cài đặt và quản lý gói tại Quy trình sử dụng gói (tài liệu NuGet). 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 (comment) trong hợp đồng .proto, như trong ví dụ sau:

// 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 gRPC OpenAPI:

1. Kích hoạt tệp tài liệu XML trong dự án máy chủ bằng <GenerateDocumentationFile>true</GenerateDocumentationFile>.
2. Định cấu hình AddSwaggerGen để đọc file XML được tạo. Truyền đường dẫn file XML tới IncludeXmlComments và IncludeGrpcXmlComments, như trong ví dụ sau:

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 dịch vụ RESTful gRPC, hãy khởi động ứng dụng và điều hướng đến trang Giao diện người dùng Swagger:

Tài nguyên bổ sung

• Chuyển mã JSON gRPC trong ứng dụng gRPC ASP.NET Core
• Trang chủ OpenAPI
• Kho lưu trữ GitHub Swashbuckle.AspNetCore