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