【swagger+yapi】proto+grpc+swagger结合yapi命令生成接口文档

【swagger+yapi】proto+grpc+swagger结合yapi命令生成接口文档 1、环境

• *** 作系统：ubuntu 18.04
• go版本：1.14.2
• docker版本：19.03.1
• docker-compose版本：1.24.0

2、gRPC环境安装

# 启用 module模式
GO111MODULE="on"
# 配置 goproxy
go env -w GOPROXY="https://goproxy.io,https://goproxy.cn,direct"
# 安装 grpc
$ go get -u google.golang.org/grpc

3、安装 Protocol Buffers v3

$ wget https://github.com/protocolbuffers/protobuf/releases/download/v3.11.4/protobuf-all-3.11.4.tar.gz
$ sudo tar -zxvf protobuf-all-3.11.4.tar.gz -C /usr/local
$ cd /usr/local/protobuf-3.11.4/
$ sudo ./configure
$ sudo make
$ sudo make install
$ sudo ldconfig

检查是否安装成功

$ protoc --version
libprotoc 3.11.4

4、安装插件 protoc-gen-go、protoc-gen-grpc-gateway、protoc-gen-swagger

go get -u github.com/golang/protobuf/protoc-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

5、编写protot文件并编译 5.1 生成swagger API 文档，需要用到google/api中http.proto、annotations.proto这两个文件，先拷贝到项目目录下

# 进入项目的根目录
$ cd /path/to/project
$ mkdir -p ./proto/google/api
$ cp -r $GOPATH/pkg/mod/github.com/grpc-ecosystem/grpc-gateway@v1.14.4/third_party/googleapis/google/api/* ./proto/google/api

5.2 编写protot文件

syntax = "proto3";

package proto;

import "google/api/annotations.proto";

// 源.proto文件应包含go_package选项，该选项指定文件的完整Go导入路径。
// 如果没有go_package选项，则编译器将尝试猜测一个。将来的编译器版本将要求go_package选项。
// 生成的代码的Go包名称将是go_package选项的最后一个路径组件。
option go_package = "../proto";

message StringMessage {
  string value = 1;
}

//定义RPC服务
service HelloService {
  rpc Hello (StringMessage) returns (StringMessage) {
    option (google.api.http) = {
      post: "/v1/hello"
      body: "*"
    };
  }
}

5.3 使用protoc命令编译生成go源码及swagger.json

# 生成proto对应的go源码
protoc --go_out=plugins=grpc:. *.proto

# 生成proto对应的swagger.json文件(/path/to/project为项目的根目录)
protoc -I /usr/local/include -I . -I /path/to/project/proto/google/api --swagger_out=logtostderr=true:. ./hello.proto

6、使用docker启动swagger ui服务，查看生成的API文档

docker run --rm -d -p 80:8080 -e SWAGGER_JSON=/foo/hello.swagger.json -v /path/to/project/proto:/foo swaggerapi/swagger-ui

访问swagger ui服务所在的主机的80端口，即可查看API文档

7、编写server.go和client.go调用RPC服务 7.1 server.go

package main

import (
	"context"
	pb "github.com/king-tu/helloGRPC/proto"
	"google.golang.org/grpc"
	"log"
	"net"
)

type HelloService struct{}

func (*HelloService) Hello(ctx context.Context, msg *pb.StringMessage) (*pb.StringMessage, error) {
	log.Println("client request message: ", msg)
	reply := &pb.StringMessage{
		Value: "hello " + msg.Value,
	}
	return reply, nil
}

func main() {
	address := ":1234"
	//获取grpc服务端对象
	grpcServer := grpc.NewServer()
	//注册grpc服务
	pb.RegisterHelloServiceServer(grpcServer, new(HelloService))

	//设置服务端监听
	lis, err := net.Listen("tcp", address)
	if err != nil {
		panic(err)
	}
	//在指定端口上提供grpc服务
	log.Println("gRPC Server listen on: ", address)
	if err := grpcServer.Serve(lis); err != nil {
		panic(err)
	}
}

7.2 client.go

package main

import (
	"context"
	pb "github.com/king-tu/helloGRPC/proto"
	"google.golang.org/grpc"
	"log"
)

func main() {
	//和grpc服务建立连接
	conn, err := grpc.Dial("localhost:1234", grpc.WithInsecure())
	if err != nil {
		panic(err)
	}
	defer conn.Close()

	client := pb.NewHelloServiceClient(conn)
	reply, err := client.Hello(context.Background(), &pb.StringMessage{Value: "lisi"})
	if err != nil {
		panic(err)
	}
	log.Println("reply: ", reply)
}

7.3 测试效果

服务端

$ go run server.go 
2020/04/28 01:04:54 gRPC Server listen on:  :1234
2020/04/28 01:05:10 client request message:  value:"lisi"

客户端

$ go run client.go 
2020/04/28 01:06:01 reply:  value:"hello lisi"

8、完整项目目录

$ tree
.
├── client
│   └── client.go
├── go.mod
├── go.sum
├── proto
│   ├── google
│   │   └── api
│   │       ├── annotations.proto
│   │       ├── httpbody.proto
│   │       └── http.proto
│   ├── hello.pb.go
│   ├── hello.proto
│   └── hello.swagger.json
└── server
    └── server.go

5 directories, 10 files

• 示例代码：helloGRPC

• Grpc+Grpc Gateway实践三 Swagger了解一下

• Swagger documentation | Swagger

参考文章：

1、PHP项目swagger结合yapi命令生成接口文档
2、当Swagger遇上YApi，瞬间高大上了！
3、Yapi —— 接口在线管理和调试工具
4、Yapi本地化部署及接口调试（亲测）
5、chrome 安装 yapi 扩展教程
6、使用go-swagger为golang API自动生成swagger文档
7、go实践之swagger自动生成api文档
8、Gin + Swagger快速生成API文档
9、go学习笔记 grpc-gateway、google api和swagger
9、go grpc protobuf restfull api swagger 安装 及 各种用法示例
10、swagger+import.json_yapi导入
11、docker下YApi部署教程-支持swagger数据导入