grpc-graphql-gateway
is a protoc plugin that generates graphql execution code from Protocol Buffers.
On API development, frequently we choose some IDL, in order to manage API definitions from a file. Considering two of IDL -- GraphQL and Protocol Buffers (for gRPC) -- these have positive point respectively:
But sometimes it's hard to maintain both GraphQL and Protocol Buffers, so we created this plugin in order to generate GraphQL Schema from Protocol Buffers.
This project much refers to grpc-gateway how to generate a file, provide a plugin. many thanks!
Get protoc-gen-graphql
binary from releases page and set $PATH to be executable.
Or, simply get the latest one:
go get github.com/ysugimoto/grpc-graphql-gateway/protoc-gen-graphql/...
Then the binary will place in $GOBIN
.
Get include/graphql.proto
from this repository and put it into your project under the protobuf files.
git submodule add https://github.com/ysugimoto/grpc-graphql-gateway.git grpc-graphql-gateway
## Or another way...
Please replace [your/project]
section to your appropriate project.
Declare gRPC service with protobuf using grpc-graphql-gateway
options.
This example has two RPCs that names SayHello
and SayGoodbye
:
// greeter.proto
syntax = "proto3";
import "graphql.proto";
service Greeter {
// gRPC service information
option (graphql.service) = {
host: "localhost:50051"
insecure: true
};
rpc SayHello (HelloRequest) returns (HelloReply) {
// Here is plugin definition
option (graphql.schema) = {
type: QUERY // declare as Query
name: "hello" // query name
};
}
rpc SayGoodbye (GoodbyeRequest) returns (GoodbyeReply) {
// Here is plugin definition
option (graphql.schema) = {
type: QUERY // declare as Query
name: "goodbye" // query name
};
}
}
message HelloRequest {
// Below line means the "name" field is required in GraphQL argument
string name = 1 [(graphql.field) = {required: true}];
}
message HelloReply {
string message = 1;
}
message GoodbyeRequest {
// Below line means the "name" field is required in GraphQL argument
string name = 1 [(graphql.field) = {required: true}];
}
message GoodbyeReply {
string message = 1;
}
Compile protobuf file with the plugin:
protoc \
-I. \
--go_out=./greeter \
--go-grpc_out=./greeter \
--graphql_out=./greeter \
greeter.proto
Then you can see greeter/greeter.pb.go
and greeter/greeter.graphql.go
.
For example, gRPC service will be:
// service/main.go
package main
import (
"context"
"fmt"
"net"
"log"
"github.com/[your/project]/greeter"
"google.golang.org/grpc"
)
type Server struct{}
func (s *Server) SayHello(ctx context.Context, req *greeter.HelloRequest) (*greeter.HelloReply, error) {
return &greeter.HelloReply{
Message: fmt.Sprintf("Hello, %s!", req.GetName()),
}, nil
}
func (s *Server) SayGoodbye(ctx context.Context, req *greeter.GoodbyeRequest) (*greeter.GoodbyeReply, error) {
return &greeter.GoodbyeReply{
Message: fmt.Sprintf("Good-bye, %s!", req.GetName()),
}, nil
}
func main() {
conn, err := net.Listen("tcp", ":50051")
if err != nil {
log.Fatal(err)
}
defer conn.Close()
server := grpc.NewServer()
greeter.RegisterGreeterServer(server, &Server{})
server.Serve(conn)
}
Then let's start service:
go run service/main.go
The gRPC service will start on localhost:50051
.
Next, GraphQL gateway service should be:
// gateway/main.go
package main
import (
"log"
"net/http"
"github.com/[your/project]/greeter"
"github.com/ysugimoto/grpc-graphql-gateway/runtime"
)
func main() {
mux := runtime.NewServeMux()
if err := greeter.RegisterGreeterGraphql(mux); err != nil {
log.Fatalln(err)
}
http.Handle("/graphql", mux)
log.Fatalln(http.ListenAndServe(":8888", nil))
}
Then let's start gateway:
go run gateway/main.go
The GraphQL gateway will start on localhost:8888
Now you can access gRPC service via GraphQL gateway!
curl -g "http://localhost:8888/graphql" -d '
{
hello(name: "GraphQL Gateway") {
message
}
}'
#=> {"data":{"hello":{"message":"Hello, GraphQL Gateway!"}}}
You can also send request via POST
method with operation name like:
curl -XPOST "http://localhost:8888/graphql" -d '
query greeting($name: String = "GraphQL Gateway") {
hello(name: $name) {
message
}
goodbye(name: $name) {
message
}
}'
#=> {"data":{"goodbye":{"message":"Good-bye, GraphQL Gateway!"},"hello":{"message":"Hello, GraphQL Gateway!"}}}
This is the most simplest way :-)
To learn more, please see the following resources:
graphql.proto
Plugin option definition. See a comment section for custom usage (e.g mutation).This plugin generates graphql execution code using graphql-go/graphql, see that repository in detail.
This plugin just aims to generate a simple gateway of gRPC.
Some of things could be solved and could not be solved. The most of limitations come from the IDL's power of expression -- some kind of GraphQL schema feature cannot implement by Protocol Buffers X(
Currently we don't support some Protobuf types:
oneof
typeYoshiaki Sugimoto
MIT