Go – integrate swagger

现有服务是用micro+protobuf+gRPC。现在每个服务都有个proto文件，完整定义了参数、传递消息及响应结果。主要实现步骤有三步

1. 用.proto文件转换为swagger.json文件
2. 合并所有swagger.json成为一个
3. Serve the API

Step 1: .proto文件转换为swagger.json文件

使用工具：https://github.com/grpc-ecosystem/grpc-gateway

Install

protoc和proto-gen-go的安装略

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

Usage

• 正常写.proto文件

syntax = "proto3";
package example;
message StringMessage {
  string value = 1;
}

service YourService {
  rpc Echo(StringMessage) returns (StringMessage) {}
}

• 添加自定义选项到这个.proto文件

 syntax = "proto3";
 package example;
+
+import "google/api/annotations.proto";
+
 message StringMessage {
   string value = 1;
 }

 service YourService {
-  rpc Echo(StringMessage) returns (StringMessage) {}
+  rpc Echo(StringMessage) returns (StringMessage) {
+    option (google.api.http) = {
+      post: "/v1/example/echo"
+      body: "*"
+    };
+  }
 }

• 生成 swagger.json文件

protoc -I/usr/local/include -I. \
    -I$GOPATH/src \
    -I$GOPATH/src/github.com/grpc-ecosystem/grpc-gateway/third_party/googleapis \
    -I$GOPATH/src/github.com/grpc-ecosystem/grpc-gateway \
    --swagger_out=logtostderr=true:. \
    path/to/your_service.proto

增加更多的swagger注释

import "google/api/annotations.proto";  
import "protoc-gen-swagger/options/annotations.proto";

// 概要
option (grpc.gateway.protoc_gen_swagger.options.openapiv2_swagger) = {
    info: {
        title: "go-service"
        version : "1.0.0"
        description: "gRPC服务用"
    };
    schemes: HTTP
    consumes: "application/json"
    produces: "application/json"
};

// 服务介绍，tag
service YourService {
    rpc Echo(RequestById) returns (City) {
        option (google.api.http) = {
            post: "/v1/example/echo"
            body: "*"
        };
        option (grpc.gateway.protoc_gen_swagger.options.openapiv2_operation) = {
            summary: "详情"
            tags: "example"
        };
    }
}

更多可配置的可参照这里：github.com/grpc-ecosystem/grpc-gateway/protoc-gen-swagger/options/openapiv2.proto

Step 2: 合并swagger.json文件

每个proto文件只能生成一个json文件，因此需要把各个json文件合并成一个。
使用工具：https://github.com/go-swagger/go-swagger

Install

brew tap go-swagger/go-swagger
brew install go-swagger

Usage

主要使用mixin命令

swagger mixin {spec1} {spec2}

为了方便可以写个bash脚本，把所有生成的*.swagger.json文件合并起来。

Step 3: Serve the API

swagger serve swagger.json 
swagger serve swagger.json -Fswagger

第一个只能看文档
第二个会引导你打开某链接，实际是swagger ui的live demo
为了“try it out”能成功，不要忘记在swagger.json里加入host和basePath。

服务器上搭就是拉了份swagger UI，把host的url改为了这个swagger.json可以访问的地址，即可。

其它改动：

以前用来生成stub的命令要增加path：

比如，before:

protoc -I$GOPATH/src:. --micro_out=. --go_out=. path/to/your_service.proto

after:

protoc -I/usr/local/include -I. \
    -I$GOPATH/src \
    -I$GOPATH/src/github.com/grpc-ecosystem/grpc-gateway/third_party/googleapis \
    -I$GOPATH/src/github.com/grpc-ecosystem/grpc-gateway \
    --micro_out=. --go_out=. \
    path/to/your_service.proto