Merge pull request #5698 from gyuho/documentation

Documentation: grpc-gateway

Documentation/dev-guide/api_grpc_gateway.md

@@ -0,0 +1,38 @@
+
+## Why grpc-gateway
+
+etcd v3 uses [gRPC][grpc] for its messaging protocol. The etcd project includes a gRPC-based [Go client][go-client] and a command line utility, [etcdctl][etcdctl], for communicating with an etcd cluster through gRPC. For languages with no gRPC support, etcd provides a JSON [grpc-gateway][grpc-gateway]. This gateway serves a RESTful proxy that translates HTTP/JSON requests into gRPC messages.
+
+
+## Using grpc-gateway
+
+The gateway accepts a [JSON mapping][json-mapping] for etcd's [protocol buffer][api-ref] message definitions. Note that `key` and `value` fields are defined as byte arrays and therefore must be base64 encoded in JSON.
+
+```bash
+<<COMMENT
+https://www.base64encode.org/
+foo is 'Zm9v' in Base64
+bar is 'YmFy'
+COMMENT
+
+curl -L http://localhost:2379/v3alpha/kv/put \
+	-X POST -d '{"key": "Zm9v", "value": "YmFy"}'
+
+curl -L http://localhost:2379/v3alpha/kv/range \
+	-X POST -d '{"key": "Zm9v"}'
+```
+
+
+## Swagger
+
+Generated [Swapper][swagger] API definitions can be found at [rpc.swagger.json][swagger-doc].
+
+[api-ref]: ./api_reference_v3.md
+[go-client]: https://github.com/coreos/etcd/tree/master/clientv3
+[etcdctl]: https://github.com/coreos/etcd/tree/master/etcdctl
+[grpc]: http://www.grpc.io/
+[grpc-gateway]: https://github.com/gengo/grpc-gateway
+[json-mapping]: https://developers.google.com/protocol-buffers/docs/proto3#json
+[swagger]: http://swagger.io/
+[swagger-doc]: apispec/swagger/rpc.swagger.json
+

Documentation/docs.md

@@ -13,6 +13,7 @@ The easiest way to get started using etcd as a distributed key-value store for y
  - [Setting up local clusters][local_cluster]
  - [Interacting with etcd][interacting]
  - [API references][api_ref]
+ - [gRPC gateway][api_grpc_gateway]
 
 ## Operating etcd clusters
 
@@ -44,6 +45,7 @@ To learn more about the concepts and internals behind etcd, read the following p
 ## Troubleshooting
 
 [api_ref]: dev-guide/api_reference_v3.md
+[api_grpc_gateway]: dev-guide/api_grpc_gateway.md
 [clustering]: op-guide/clustering.md
 [conf]: op-guide/configuration.md
 [demo]: demo.md

scripts/genproto.sh

@@ -49,6 +49,7 @@ popd
 
 # generate gateway code
 go get -u github.com/gengo/grpc-gateway/protoc-gen-grpc-gateway
+go get -u github.com/gengo/grpc-gateway/protoc-gen-swagger
 pushd "${GRPC_GATEWAY_ROOT}"
 	git reset --hard "${GRPC_GATEWAY_SHA}"
 	go install ./protoc-gen-grpc-gateway
@@ -70,7 +71,17 @@ done
 protoc -I. \
     -I${GRPC_GATEWAY_ROOT}/third_party/googleapis \
     -I${GOGOPROTO_PATH} \
-    -I${COREOS_ROOT} --grpc-gateway_out=logtostderr=true:. ./etcdserver/etcdserverpb/rpc.proto
+    -I${COREOS_ROOT} \
+    --grpc-gateway_out=logtostderr=true:. \
+    --swagger_out=logtostderr=true:./Documentation/dev-guide/apispec/swagger/. \
+    ./etcdserver/etcdserverpb/rpc.proto
+
+# TODO: change this whenever we add more swagger API
+mv \
+	Documentation/dev-guide/apispec/swagger/etcdserver/etcdserverpb/rpc.swagger.json \
+	Documentation/dev-guide/apispec/swagger/rpc.swagger.json
+rm -rf Documentation/dev-guide/apispec/swagger/etcdserver/etcdserverpb
+
 
 # install protodoc
 # go get -v -u github.com/coreos/protodoc