gRPC-GateWay Swagger 实战

上一次我们分享了关于 gRPC-Gateway 快速实战 ，可以查看地址来进行回顾 :

也可以查看关于 gRPC 的历史文章：

• gRPC介绍

• gRPC 客户端调用服务端需要连接池吗？

• gRPC的拦截器

• gRPC的认证

• 分享一下 gRPC- HTTP网关 I

今天主要是分享关于 gRPC-Gateway Swagger 的实战部分，文章大体分为如下几个部分：

• 基本环境补充

• gRPC-GateWay Swagger 实战

基本环境补充

首先，我们来看一下环境搭建完毕和完成实战之后的目录结构

[图片上传失败...(image-619e40-1693563576675)]

通过目录结构我们可以看到：

• my_grpcgateway 目录下多了 pkg 目录

这个目录是通过工具生成的，主要是处理 swagger 的 go 文件

• my_grpcgateway/protoc/order/order.swagger.json

工具生成的 swagger.json 文件，里面记录了关于 swagger 的接口 和 配置相关信息

• my_grpcgateway/protoc/order/protoc-gen-swagger

protoc-gen-swagger 工具目录

• my_grpcgateway/third_party

swagger 的资源目录

那么我们就动起手来，一个一个的将上述的内容填充起来吧：

1. 安装 Protoc Plugin

go get -u github.com/grpc-ecosystem/grpc-gateway/protoc-gen-swagger

执行完毕之后，我们可以在我们的 GOPATH 目录下找到 protoc-gen-swagger 目录

[图片上传失败...(image-155e0d-1693563576675)]

此时，我们将 protoc-gen-swagger 目录拷贝到我们的 my_grpcgateway/order/protoc 下

cd my_grpcgateway/order/protoc 
cp /root/go/pkg/mod/github.com/grpc-ecosystem/grpc-gateway@v1.16.0/protoc-gen-swagger ./ -rf

2. 下载 swagger-ui 的静态资源

进入地址 ：https://github.com/swagger-api/swagger-ui 将项目代码 download 下来

[图片上传失败...(image-ce7df5-1693563576675)]

然后再我们自己的项目目录 my_grpcgateway 下创建 third_party/swagger-ui 目录

mkdir third_party/swagger-ui/

最后将上述 swagger-ui 的 dist 目录下的所有内容，拷贝到我们自己的 third_party/swagger-ui 目录下

cp xx/dist/*  my_grpcgateway/third_party/swagger-ui/

3. 安装必要的静态资源转换包

第一，先下载 go-bindata，用处是 go-bindata 用来将 swagger-ui 的源码转为 GO 代码

go get -u github.com/jteeuwen/go-bindata/...

第二，下载 go-bindata-assetfs，用处是 go-bindata-assetfs 能够结合 net/http 标准库和 go-bindata 所生成 Swagger UI 的 Go 代码两者来供外部访问 ，也就是说 go-bindata-assetfs 可以对外提供文件服务，这样可以通过web访问swagger的 json 文件

go get -u github.com/elazarl/go-bindata-assetfs/...

4. 在 my_grpcgateway 目录下新建 pkg 目录，并使用工具在 pkg 目录下新增 swagger-ui 涉及的代码

cd my_grpcgateway 
mkdir pkg
go-bindata --nocompress -pkg swagger -o pkg/ui/data/swagger/datafile.go third_party/swagger-ui/...

执行完毕之后，我们就可以在my_grpcgateway/pkg 目录下看到这样的目录结构了

[图片上传失败...(image-9e81-1693563576675)]

关于环境的看到此处即可，剩下的就来开始 gRPC-GateWay Swagger 实战吧，再次动起手来干

gRPC-GateWay Swagger 实战

本次的 gRPC-GateWay Swagger 实战 是基于上次的 gRPC-GateWay 快速实战的项目代码的

1. 修改 my_grpcgateway/protoc/order/order.proto 代码

[图片上传失败...(image-31bf9-1693563576675)]

这个时候我们可以关注到，proto 的如下几个变化：

• 我们新导入了包import "protoc-gen-swagger/options/annotations.proto";

• Proto 文件中我们新加入了 swagger 的定义

// 定义swagger内容
option (grpc.gateway.protoc_gen_swagger.options.openapiv2_swagger) = {
  info: {
                title: "grpc gateway order sample";
                version: "1.0";
  };
  schemes: HTTP;
};

此处咱们将 schemes 设定为 HTTP 的，本次我们不演示 HTTPS

2. 使用工具生成 order.swagger.json 文件

protoc -I ./ \
  --go_out ./ --go_opt paths=source_relative \
  --go-grpc_out ./ --go-grpc_opt paths=source_relative \
  --grpc-gateway_out ./ --grpc-gateway_opt paths=source_relative \
  --swagger_out=logtostderr=true:. \
  ./order.proto

上述命令前面几行和之前都是一样的，本次主要是关注这句话

--swagger_out=logtostderr=true:. \

至此，上述环境准备中说到的 4 个变化点，我们都已经准备完毕，下面开始 swagger 相关的代码编写

[图片上传失败...(image-a34843-1693563576675)]

3. 编写我们的服务，并把 swagger 加上去

• 修改 my_grpcgateway/main.go 文件，调用我们的 RunGrpcGwWithSwagger 接口 来启动 grpc-gateway 服务并带上 swagger

[图片上传失败...(image-d3ed04-1693563576675)]

• 修改我们的 my_grpcgateway/server/server.go 文件，新加一个 RunGrpcGwWithSwagger 函数，里面处理 关于 swagger 相关内容

my_grpcgateway/server/server.go

[图片上传失败...(image-834f7b-1693563576675)]

[图片上传失败...(image-5bee4c-1693563576675)]

上述代码不难，应用起来也很简单，我们可以看出咱们本次对外提供了 2 个接口

• http://localhost:9999/swagger/order.swagger.json

访问这个接口，实际上是请求到了 ******order.swagger.json** ****文件的具体内容，此处的处理逻辑是 svrSwaggerFile 函数会将 ******swagger.json** 过滤出来，并加上相对路径 ./protoc/order/ ，实际上就访问到了我们服务项目目录中的 my_grpcgateway/protoc/order/order.swagger.json

• http://localhost:9999/swagger-ui/

请求上述接口，我们就可以看到咱们 swagger ui 界面了，这个时候，其实我们看到的接口并不是我们自己写的接口

因此如图中的查询路径目前是默认的

[图片上传失败...(image-e5842f-1693563576675)]

这个时候，我们将搜索框中的内容修改成 http://localhost:9999/swagger/order.swagger.json

[图片上传失败...(image-659bab-1693563576675)]

此时，我们就可以看到我们自己编写的接口内容了，关于 swagger 我们是可以在 swagger-ui 界面进行接口请求的，这里就简单指引一下，其他的就不赘述的了

第一，点击 Try it out

[图片上传失败...(image-ba3c76-1693563576675)]

第二，填写咱们的请求参数

[图片上传失败...(image-d2b896-1693563576675)]

第三，点击 Execute 之后，查看咱们的响应结果

[图片上传失败...(image-156616-1693563576675)]

至此，关于 gRPC-GateWay Swagger 实战 就分享到此处，项目代码可以查看：https://github.com/qingconglaixueit/my_grpcgateway_demo

感谢阅读，欢迎交流，点个赞，关注一波 再走吧

欢迎点赞，关注，收藏

朋友们，你的支持和鼓励，是我坚持分享，提高质量的动力

[图片上传失败...(image-342885-1693563576675)]

好了，本次就到这里

技术是开放的，我们的心态，更应是开放的。拥抱变化，向阳而生，努力向前行。

我是阿兵云原生，欢迎点赞关注收藏，下次见~