.NET7 gRPC JSON轉碼+OpenAPI

gRPC JSON轉碼

gRPC JSON 轉碼允許瀏覽器應用呼叫 gRPC 服務，就像它們是使用 JSON 的 RESTful API 一樣。

瀏覽器應用不需要生成 gRPC 使用者端或瞭解 gRPC 的任何資訊。
通過使用 HTTP 後設資料註釋 .proto 檔案，可從 gRPC 服務自動建立 RESTful API。
使應用可以同時支援 gRPC 和 JSON Web API，而無需重複為兩者生成單獨的服務。

OpenAPI與gRPC Server

OpenAPI（以前稱為 Swagger）是一個與語言無關的規範，用於描述 API。 gRPC JSON 轉碼支援從轉碼 REST ful的 API 生成 OpenAPI。

實現Server端

通過VS新增GRPC Server，新增nuget包

  <ItemGroup>
    <PackageReference Include="Grpc.AspNetCore" Version="2.49.0" />
    <PackageReference Include="Microsoft.AspNetCore.Grpc.JsonTranscoding" Version="7.0.0" />
    <PackageReference Include="Microsoft.AspNetCore.Grpc.Swagger" Version="0.3.0" />
  </ItemGroup>

為api生成用於OpenAPI的註釋XML檔案，在Server.csproj檔案中新增以下設定

<GenerateDocumentationFile>true</GenerateDocumentationFile>

Server的Program.cs中，開啟JSON轉碼與Swagger

            var builder = WebApplication.CreateBuilder(args);

            // 開啟JSON轉碼
            builder.Services.AddGrpc().AddJsonTranscoding();

            // 設定Swagger
            builder.Services.AddGrpcSwagger();
            builder.Services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", new OpenApiInfo { Title = "gRPC transcoding", Version = "v1" });
                var filePath = Path.Combine(System.AppContext.BaseDirectory, "GrpcService4.xml");
                c.IncludeXmlComments(filePath);
                c.IncludeGrpcXmlComments(filePath, includeControllerXmlComments: true);
            });

            var app = builder.Build();

            //開啟Swagger
            app.UseSwagger();
            app.UseSwaggerUI(c =>
            {
                c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
            });

            app.MapGrpcService<GreeterService>();
            app.MapGet("/", () => "Communication with gRPC endpoints must be made through a gRPC client. To learn how to create a client, visit: https://go.microsoft.com/fwlink/?linkid=2086909");

            app.Run();

下載GRPC JSON轉碼依賴的proto檔案

https://github.com/dotnet/aspnetcore/blob/main/src/Grpc/JsonTranscoding/test/testassets/Sandbox/google/api/http.proto

https://github.com/dotnet/aspnetcore/blob/main/src/Grpc/JsonTranscoding/test/testassets/Sandbox/google/api/annotations.proto

並將檔案放到專案的google/api/資料夾中。

修改greet.proto檔案，通過option開啟http選項，以一個get方法和一個post方法舉例

syntax = "proto3";

import "google/api/annotations.proto";

option csharp_namespace = "GrpcService4";

package greet;

// The greeting service definition.
service Greeter {
  // Sends a greeting
  rpc SayHello (HelloRequest) returns (HelloReply){
     option (google.api.http) = {
      get: "/v1/greeter/{name}"
    };
  };

    // Sends a greeting
  rpc SayHelloPost (HelloRequestPost) returns (HelloReply){
     option (google.api.http) = {
      post: "/v1/greeter/post",
      body:"data"
    };
  };
}

// The request message containing the user's name.
message HelloRequest {
  string name = 1;
}

// The request message containing the user's name.
message HelloRequestPost {
  HelloRequestPostData data = 1;
}

message HelloRequestPostData{
    string name = 1;
    string gender = 2;
}

// The response message containing the greetings.
message HelloReply {
  string message = 1;
}

然後實現Server

using Grpc.Core;
using GrpcService4;

namespace GrpcService4.Services
{
    public class GreeterService : Greeter.GreeterBase
    {
        private readonly ILogger<GreeterService> _logger;
        public GreeterService(ILogger<GreeterService> logger)
        {
            _logger = logger;
        }

        public override Task<HelloReply> SayHello(HelloRequest request, ServerCallContext context)
        {
            return Task.FromResult(new HelloReply
            {
                Message = "Hello " + request.Name
            });
        }


        public override Task<HelloReply> SayHelloPost(HelloRequestPost request, ServerCallContext context)
        {
            return Task.FromResult(new HelloReply
            {
                Message = "Hello " + request.Data.Name
            });
        }
    }
}

至此server的json轉碼開啟完成，執行服務，存取swagger，即可嘗試http方式請求

在支援http方式的請求的情況下，同時支援grpc請求。

實現Client端

新增控制檯專案，新增以下nuget

  <ItemGroup>
    <PackageReference Include="Google.Protobuf" Version="3.21.9" />
    <PackageReference Include="Grpc.Net.Client" Version="2.49.0" />
    <PackageReference Include="Microsoft.AspNetCore.Grpc.JsonTranscoding" Version="7.0.0" />
    <PackageReference Include="Grpc.Tools" Version="2.50.0">
      <PrivateAssets>all</PrivateAssets>
      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
    </PackageReference>
  </ItemGroup>

包含與server端相同的proto檔案

  <ItemGroup>
    <Protobuf Include="Protos\greet.proto" GrpcServices="Client" />
  </ItemGroup>

嘗試請求Server

        static async Task Main(string[] args)
        {
            using var channel = GrpcChannel.ForAddress("https://localhost:7167");
            var client = new Greeter.GreeterClient(channel);
            var reply = await client.SayHelloAsync(new HelloRequest { Name = "GreeterClient" });
            Console.WriteLine("Greeting: " + reply.Message);

            var replyPost = await client.SayHelloPostAsync(new HelloRequestPost { Data = new HelloRequestPostData { Name = "111" } });
            Console.WriteLine("Greeting: " + replyPost.Message);
            Console.WriteLine("Press any key to exit...");
            Console.ReadKey();
        }

source code: https://github.com/cysnet/grpc-json-transcoding