关于.Net 7.0 RC gRPC JSON 转码为 Swagger/OpenAPI文档的注意事项

大家好，我是失业在家，正在找工作的博主Jerry，找工作之余，看到.Net 7.0 RC2发布了，就想测试下.Net 7.0 RC2 gRPC JSON 转码为 Swagger/OpenAPI文档的特性，这个特性大大提高了测试gRPC接口的方便性。本来以为按照官方文档，也就是几分钟的事，结果搞了几个小时才成功！我也是服了官方的文档了！

我现在把要要注意的几个问题列出来，给要使用这个特性的程序员节约一点时间。

一、官方文档对gRPC JSON 转码配置描述不完整

这个特性是基于gRPC JSON 转码配置的，也就是说我们先要配置gRPC JSON 转码才能使用该特性。

// Add services to the container.
builder.Services.AddGrpc().AddJsonTranscoding();

如上我们在Program.cs中的代码，先要先加上gRPC JSON转码。如果按照官方文档直接在.proto文件的rpc方法中增加option

 option (google.api.http) = {
      get: "/v1/greeter/{name}"
    };

则编译会报错，“Option "(google.api.http)" unknown. Ensure that your proto definition file imports the proto which defines the option.”

要先按照另一个官方文档专门配置gRPC JSON转码。要在.proto文件中增加“import "google/api/annotations.proto";

import "google/api/annotations.proto";

二、官方文档对gRPC JSON 转码配置描述不清楚

加上了import..., 还是会编译出错，"Import "google/api/annotations.proto" was not found or had errors.".

原因就是文档里的这一句“Imported from the google/api/annotations.proto file. The google/api/http.proto and google/api/annotations.proto files need to be in the project.”实在说的不清楚。

其实，我们要在我们项目的根目录建立google文件夹，然后在下面建立api文件夹，再把这两个文件放到里面。如下截图：

然后还要确保项目文件中，不要把这两个文件包含到Protobuf节点中。不然在启动程序的时候就会出现对象转换失败的错误，“[A]Google.Protobuf.ExtensionValue`1[Google.Api.HttpRule] cannot be cast to [B]Google.Protobuf.ExtensionValue`1[Google.Api.HttpRule]. Type A originates from 'Google.Protobuf, Version=3.19.4.0, Culture=neutral, PublicKeyToken=a7d26565bac4d604' in the context 'Default' at location 'D:\\Study\\Test\\GrpcService4TestSwagger\\bin\\Debug\\net7.0\\Google.Protobuf.dll'. Type B originates from 'Google.Protobuf, Version=3.19.4.0, Culture=neutral, PublicKeyToken=a7d26565bac4d604' in the context 'Default' at location 'D:\\Study\\Test\\GrpcService4TestSwagger\\bin\\Debug\\net7.0\\Google.Protobuf.dll'”

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

这样就算配置gRPC JSON转码完成了，程序终于可以运行起来了。

三、官方文档上的代码片段不正确

这时候，如果你访问Swagger的页面还是会出错，“System.IO.FileNotFoundException:“Could not find file 'D:\Study\Test\GrpcService4TestSwagger\bin\Debug\net7.0\Server.xml”，我真是服了这个官方文档了，要把官方文档给的代码：

var filePath = Path.Combine(System.AppContext.BaseDirectory, "Server.xml");
    c.IncludeXmlComments(filePath);
    c.IncludeGrpcXmlComments(filePath, includeControllerXmlComments: true);

改成这样才行：

 var xmlFilename = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var filePath = Path.Combine(AppContext.BaseDirectory, xmlFilename);
    c.IncludeXmlComments(filePath);
    c.IncludeGrpcXmlComments(filePath, includeControllerXmlComments: true);

终于， gRPC JSON 转码为 Swagger/OpenAPI文档的特性可以成功运行了。

四、找工作

博主有15年以上的软件技术实施经验（Technical Leader），专注于微服务和云原生（K8s）软件架构设计、专注于 .Net Core\Java开发和Devops构建发布。
博主10年以上的软件交付管理经验（Project Manager & Product Ower），致力于敏捷（Scrum）项目管理、软件产品业务需求分析和原型设计。
博主熟练配置和使用 Microsoft Azure云。
博主为人诚恳，积极乐观，工作认真负责。

我家在广州，也可以去深圳工作。做架构和项目管理都可以。有工作机会推荐的朋友可以加我微信 15920128707，微信名字叫Jerry。