Add docs using mkdocs (#49)

* docs: add mkdocs config and split the existing readme into separate docs

* fix: make examples work again

* fix: make examples work again

* fix: make examples work again

.github/workflows/master.yml

@@ -3,12 +3,10 @@ name: Go
 on: [ push ]
 
 jobs:
-
-  build:
-    name: Build
+  tests:
+    name: Tests
     runs-on: ubuntu-latest
     steps:
-
       - name: Set up Go 1.x
         uses: actions/setup-go@v2
         with:
@@ -18,10 +16,7 @@ jobs:
       - name: Check out code into the Go module directory
         uses: actions/checkout@master
 
-      - name: Build
-        run: CGO_ENABLED=0 GOOS=linux go build -v ./cmd/gateway
-
-      - name: Test and coverage
+      - name: Run tests with coverage
         run: |
           go test -v `go list ./... | grep -v example | grep -v tools` -coverprofile=coverage.tmp.txt -covermode=atomic -coverpkg=github.com/danielvladco/go-proto-gql/...
           cat coverage.tmp.txt | grep -v .pb.go > coverage.txt
@@ -34,6 +29,79 @@ jobs:
           flags: unittests
           name: codecov-umbrella
 
+  sanity_checks:
+    name: Sanity checks
+    runs-on: ubuntu-latest
+    steps:
+      - name: Set up Go 1.x
+        uses: actions/setup-go@v2
+        with:
+          go-version: ^1.16
+        id: go
+
+      - name: Check out code into the Go module directory
+        uses: actions/checkout@master
+
+      - name: Go fmt
+        run: |
+          go fmt ./...
+
+          files=$(git diff --name-only)
+          if [[ -n $files ]]; then
+            echo "The following files are not formatted correctly:"
+            echo $files
+            exit 1
+          fi
+      - name: Go mod is tidy
+        run: |
+          go mod tidy
+          pushd example/codegen
+          go mod tidy
+          popd 
+          pushd example/codegen/api
+          go mod tidy
+          popd
+          
+          files=$(git diff --name-only)
+          if [[ -n $files ]]; then
+            echo "Detected changes to the files after mod tidy (please run `go mod tidy` and push again):"
+            echo $files
+            exit 1
+          fi
+
+      - name: Generated files are up to date
+        run: |
+          make
+          pushd example/codegen/api
+          make
+          popd 
+          pushd example/gateway
+          make
+          popd
+          
+          files=$(git diff --name-only)
+          if [[ -n $files ]]; then
+            echo "Detected changes to the files after generating (please run make and push again):"
+            echo $files
+            exit 1
+          fi
+
+  build_push_gateway:
+    name: Build & Push Gateway
+    runs-on: ubuntu-latest
+    steps:
+      - name: Set up Go 1.x
+        uses: actions/setup-go@v2
+        with:
+          go-version: ^1.16
+        id: go
+
+      - name: Check out code into the Go module directory
+        uses: actions/checkout@master
+
+      - name: Build
+        run: CGO_ENABLED=0 GOOS=linux go build -v ./cmd/gateway
+
       - name: Build and push Docker images
         uses: docker/build-push-action@v1.1.0
         with:
@@ -44,7 +112,7 @@ jobs:
           # Server address of Docker registry. If not set then will default to Docker Hub
           registry: docker.pkg.github.com
           # Docker repository to tag the image with
-          repository: ${{ github.repository }}danielvladco/go-proto-gql/gateway
+          repository: ${{ github.repository }}/gateway
           # Comma-delimited list of tags. These will be added to the registry/repository to form the image's tags
           tag_with_sha: true
           tag_with_ref: true

Dockerfile

@@ -3,8 +3,6 @@ FROM scratch
 WORKDIR /opt
 
 COPY gateway ./gateway
-COPY ./cmd/gateway/test.yaml config.yaml
 
-ENTRYPOINT ["./gateway", "--cfg", "./config.yaml"]
-
-CMD ["./gateway", "--cfg", "./config.yaml"]
+ENTRYPOINT ["./gateway"]
+CMD ["./gateway"]

README.md

@@ -0,0 +1,24 @@
+[![codecov](https://codecov.io/gh/danielvladco/go-proto-gql/branch/refactor-and-e2e-tests/graph/badge.svg?token=L3N8kUGpGV)](https://codecov.io/gh/danielvladco/go-proto-gql)
+
+This project aims to solve the problem of communication between services that use different API protocols. 
+Such as GraphAL and gRPC.
+
+Let's say your backend services use gRPC for fast and reliable communication however your frontend uses GraphQL.
+Normally your only two options:
+
+1. Either expose gRPC endpoints alongside GraphQL endpoints or build and
+2. Maintain another service that acts as a gateway between your backend infrastructure and frontend application.
+
+This project provides tools to help you build your API much quicker for both of these cases.
+
+1. Use `protoc-gen-gql`, `protoc-gen-gogql` and `proto2graphql` to generate boilerplate code on your backend.
+2. Spin up a gateway and convey the messages from one protocol to the other on the fly!
+
+Check out the docs for getting started and usage examples at: https://danielvladco.github.io/go-proto-gql/
+
+## Community:
+Will be happy for any contributions. So feel free to create issues, forks and PRs.
+
+## License:
+
+`go-proto-gql` is released under the Apache 2.0 license. See the LICENSE file for details.

cmd/gateway/main.go

@@ -12,17 +12,19 @@ import (
 )
 
 var (
-	configFile = flag.String("cfg", "/opt/config.json", "")
+	configFile = flag.String("config", "", "The config file (if not set will use the default configuration)")
 )
 
 func main() {
 	flag.Parse()
 
-	f, err := os.Open(*configFile)
-	fatalOnErr(err)
-	cfg := &server.Config{}
-	err = yaml.NewDecoder(f).Decode(cfg)
-	fatalOnErr(err)
+	cfg := server.DefaultConfig()
+	if *configFile != "" {
+		f, err := os.Open(*configFile)
+		fatalOnErr(err)
+		err = yaml.NewDecoder(f).Decode(cfg)
+		fatalOnErr(err)
+	}
 
 	l, err := net.Listen("tcp", cfg.Address)
 	fatalOnErr(err)

cmd/protogql/main.go → cmd/proto2graphql/main.go

@@ -2,23 +2,23 @@ package main
 
 import (
 	"flag"
-	"github.com/danielvladco/go-proto-gql/pkg/protoparser"
-	"google.golang.org/protobuf/compiler/protogen"
-	"google.golang.org/protobuf/types/pluginpb"
 	"log"
 	"os"
 	"path"
 	"path/filepath"
 	"strings"
 
 	"github.com/danielvladco/go-proto-gql/pkg/generator"
+	"github.com/danielvladco/go-proto-gql/pkg/protoparser"
 	"github.com/vektah/gqlparser/v2/formatter"
+	"google.golang.org/protobuf/compiler/protogen"
+	"google.golang.org/protobuf/types/pluginpb"
 )
 
 type arrayFlags []string
 
 func (i *arrayFlags) String() string {
-	return "str list"
+	return strings.Join(*i, ",")
 }
 
 func (i *arrayFlags) Set(value string) error {
@@ -35,14 +35,14 @@ var (
 )
 
 func main() {
-	flag.Var(&importPaths, "I", "path")
-	flag.Var(&fileNames, "f", "path")
+	flag.Var(&importPaths, "I", "Specify the directory in which to search for imports. May be specified multiple times. May be specified multiple times.")
+	flag.Var(&fileNames, "f", "Parse proto files and generate graphql based on the options given. May be specified multiple times.")
 	flag.Parse()
 	descs, err := protoparser.Parse(importPaths, fileNames)
 	fatal(err)
 	p, err := protogen.Options{}.New(&pluginpb.CodeGeneratorRequest{
-		FileToGenerate:  fileNames,
-		ProtoFile:       generator.ResolveProtoFilesRecursively(descs).AsFileDescriptorProto(),
+		FileToGenerate: fileNames,
+		ProtoFile:      generator.ResolveProtoFilesRecursively(descs).AsFileDescriptorProto(),
 	})
 	fatal(err)
 	gqlDesc, err := generator.NewSchemas(descs, *merge, *svc, p)

docs/1.protoc-gen-gql.md

@@ -0,0 +1,41 @@
+# Plugin protoc-gen-gql
+
+`protoc-gen-gql` plugin will generate graphql files with extension `.graphqls`
+rather than go code which means it can be further used for any other language or framework.
+
+> :warning: The GraphQL objects will only be generated for the gRPC messages of other types that are used in a service either as a input value or a return value (For details check #1)
+
+## Install
+
+```sh
+go install github.com/danielvladco/go-proto-gql/protoc-gen-gql@latest
+```
+
+The protoc compiler expects to find plugins named `proto-gen-<PLUGIN_NAME>` on the execution `$PATH`.
+
+So first add golang bin directory to the path if it's not already added (also add it to `.zshrc` or `~/.bash_profile` depending on the OS you use):
+
+```sh
+export PATH=${PATH}:$(go env GOPATH)/bin
+```
+
+## Usage
+Run the `protoc` command with the arguments for the installed plugin:
+
+Like this:
+
+```sh
+protoc --gql_out=<ADDITIONAL_ARGUMENTS>:<PATH> -I=./api -I=. ./example/codegen/api/pb/*.proto
+```
+
+Where `ADDITIONAL_ARGUMENTS` may be provided in the form of `key=value` separated by a comma.
+
+Possible additional arguments: 
+- `svc` bool - Use service annotations for nodes corresponding to a GRPC call.
+- `merge` bool - Merge all the proto files found in one directory into one graphql file.
+- `ext` string - Extension of the graphql file, Default: '.graphql' (default "graphql").
+
+## Example
+```sh
+protoc --gql_out=svc=true:. -I=./api -I=. ./example/codegen/api/pb/*.proto
+```

docs/2.protoc-gen-gogql.md

@@ -0,0 +1,43 @@
+# Plugin protoc-gen-gogql
+
+If you still want to generate go source code instead of graphql then use
+http://github.com/99designs/gqlgen plugin, and map all the generated go types with all the generated graphql types.
+
+`protoc-gen-gogql` plugin generates methods for implementing
+`github.com/99designs/gqlgen/graphql.Marshaler` and `github.com/99designs/gqlgen/graphql.Unmarshaler` interfaces. Now proto `enum`s, `oneof`s and `map`s will work fine with graphql.
+
+This plugin also creates convenience methods that will implement generated by the `gqlgen` `MutationResolver` and `QueryResolver` interfaces.
+
+## Install
+
+```sh
+go install github.com/danielvladco/go-proto-gql/protoc-gen-gogql@latest
+```
+
+The protoc compiler expects to find plugins named `proto-gen-<PLUGIN_NAME>` on the execution `$PATH`. 
+
+So first add golang bin directory to the path if it's not already added (also add it to `.zshrc` or `~/.bash_profile` depending on the OS you use):
+
+```sh
+export PATH=${PATH}:$(go env GOPATH)/bin
+```
+
+## Usage
+Run the `protoc` command with the arguments for the installed plugin:
+
+Like this:
+
+```sh
+protoc --gql_out=<ADDITIONAL_ARGUMENTS>:<PATH> -I=./api -I=. ./example/codegen/api/pb/*.proto
+```
+
+Where `ADDITIONAL_ARGUMENTS` may be provided in the form of `key=value` separated by a comma.
+
+Possible additional arguments:
+- `svc` bool - Use service annotations for nodes corresponding to a GRPC call.
+- `merge` bool - Merge all the proto files found in one directory into one file.
+
+## Example
+```sh
+protoc --gogql_out=paths=source_relative:. -I=./api -I=. ./example/codegen/api/pb/*.proto
+```