From 1fdec7891312749bfb3c2994df154a0db4623e67 Mon Sep 17 00:00:00 2001 From: Rajiv Singh Date: Thu, 3 Dec 2020 18:04:11 +0530 Subject: [PATCH] [GSoD] Refactoring the documentation files of gRPC-Gateway (#1851) * fixed edit this page broken links * refactored md files * refactored documentation files * refactored documentation files * added requested changes * added requested changes --- ADOPTERS.md | 16 ++--- CONTRIBUTING.md | 24 ++++---- README.md | 58 ++++++++++--------- docs/_config.yml | 8 +-- docs/docs/contributing/contributing.md | 9 --- docs/docs/contributing/getting_started.md | 9 +++ docs/docs/tutorials/adding_annotations.md | 28 ++++----- docs/docs/tutorials/creating_main.go.md | 2 +- docs/docs/tutorials/generating_stubs/index.md | 2 +- .../tutorials/generating_stubs/using_buf.md | 6 +- .../generating_stubs/using_protoc.md | 2 +- docs/docs/tutorials/index.md | 2 +- docs/docs/tutorials/introduction.md | 11 ++-- docs/docs/tutorials/learn_more.md | 8 +-- docs/docs/tutorials/simple_hello_world.md | 4 +- docs/index.md | 20 +++---- 16 files changed, 108 insertions(+), 101 deletions(-) delete mode 100644 docs/docs/contributing/contributing.md create mode 100644 docs/docs/contributing/getting_started.md diff --git a/ADOPTERS.md b/ADOPTERS.md index 83d86c954e1..171c2a8afd3 100644 --- a/ADOPTERS.md +++ b/ADOPTERS.md @@ -3,14 +3,14 @@ This is a list of organizations that have spoken publicly about their adoption or production users that have added themselves (in alphabetical order): -* [Ad Hoc](http://adhocteam.us/) uses the gRPC-Gateway to serve millions of - API requests per day. -* [Chef](https://www.chef.io/) uses gRPC-Gateway to provide the user-facing - API of [Chef Automate](https://automate.chef.io/). Furthermore, the generated - OpenAPI data serves as the basis for its [API documentation](https://automate.chef.io/docs/api/). - The code is Open Source, [see `github.com/chef/automate`](https://github.com/chef/automate). -* [Scaleway](https://www.scaleway.com/en/) uses the gRPC-Gateway since 2018 to - serve millions of API requests per day [1]. +- [Ad Hoc](http://adhocteam.us/) uses the gRPC-Gateway to serve millions of + API requests per day. +- [Chef](https://www.chef.io/) uses gRPC-Gateway to provide the user-facing + API of [Chef Automate](https://automate.chef.io/). Furthermore, the generated + OpenAPI data serves as the basis for its [API documentation](https://automate.chef.io/docs/api/). + The code is Open Source, [see `github.com/chef/automate`](https://github.com/chef/automate). +- [Scaleway](https://www.scaleway.com/en/) uses the gRPC-Gateway since 2018 to + serve millions of API requests per day [1]. If you have adopted the gRPC-Gateway and would like to be included in this list, feel free to submit a PR. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 31e60f2baa2..87ff509ac11 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,6 @@ # How to contribute -Thank you for your contribution to grpc-gateway. +Thank you for your contribution to gRPC-Gateway. Here's the recommended process of contribution. 1. `go get github.com/grpc-ecosystem/grpc-gateway/protoc-gen-grpc-gateway` @@ -16,13 +16,13 @@ Here's the recommended process of contribution. When you work on a larger contribution, it is also recommended that you get in touch with us through the issue tracker. -### Code reviews +## Code reviews All submissions, including submissions by project members, require review. -### I want to regenerate the files after making changes +## I want to regenerate the files after making changes -#### Using Docker +### Using Docker It should be as simple as this (run from the root of the repository): @@ -42,7 +42,7 @@ docker run -itv $(pwd):/grpc-gateway -w /grpc-gateway --entrypoint /bin/bash --r You may need to authenticate with GitHub to pull `docker.pkg.github.com/grpc-ecosystem/grpc-gateway/build-env`. You can do this by following the steps on the [GitHub Package docs](https://help.github.com/en/packages/using-github-packages-with-your-projects-ecosystem/configuring-docker-for-use-with-github-packages#authenticating-to-github-packages). -#### Using Visual Studio Code dev containers +### Using Visual Studio Code dev containers This repo contains a `devcontainer.json` configuration that sets up the build environment in a container using [VS Code dev containers](https://code.visualstudio.com/docs/remote/containers). If you're using the dev container, @@ -58,22 +58,22 @@ $ bazel run :gazelle -- update-repos -from_file=go.mod -to_macro=repositories.bz bazel run :buildifier ``` -Note that the above listed docker commands will not work in the dev container, since volume mounts from -nested docker container are not possible. +Note that the above-listed docker commands will not work in the dev container, since volume mounts from +nested docker container is not possible. If this has resulted in some file changes in the repo, please ensure you check those in with your merge request. -### Making a release +## Making a release To make a release, follow these steps: 1. Decide on a release version. The `gorelease` job can - recommend whether the new release should be a patch or minor release. - See [CircleCI](https://app.circleci.com/pipelines/github/grpc-ecosystem/grpc-gateway/126/workflows/255a8a04-de9c-46a9-a66b-f107d2b39439/jobs/6428) - for an example. + recommend whether the new release should be a patch or minor release. + See [CircleCI](https://app.circleci.com/pipelines/github/grpc-ecosystem/grpc-gateway/126/workflows/255a8a04-de9c-46a9-a66b-f107d2b39439/jobs/6428) + for an example. 1. Generate a GitHub token with `repo` access. 1. Create a new branch and edit the Makefile `changelog` job, settings - the `future-release=` variable to the name of the version you plan to release + the `future-release=` variable to the name of the version you plan to release 1. Run `CHANGELOG_GITHUB_TOKEN= make changelog` 1. Commit the `Makefile` and `CHANGELOG.md` changes. 1. Open a PR and check that everything looks right. diff --git a/README.md b/README.md index 916cbfa4291..e40353b26ad 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,19 @@ -# grpc-gateway +
+

gRPC-Gateway

+

grpc-gateway +gRPC to JSON proxy generator following the gRPC HTTP spec +

+ + + + + + +
-[![circleci](https://img.shields.io/circleci/build/github/grpc-ecosystem/grpc-gateway?color=379c9c&logo=circleci&logoColor=ffffff&style=flat-square)](https://circleci.com/gh/grpc-ecosystem/grpc-gateway) -[![codecov](https://img.shields.io/codecov/c/github/grpc-ecosystem/grpc-gateway?color=379c9c&logo=codecov&logoColor=ffffff&style=flat-square)](https://codecov.io/gh/grpc-ecosystem/grpc-gateway) -[![slack](https://img.shields.io/badge/slack-grpc--gateway-379c9c?logo=slack&logoColor=ffffff&style=flat-square)](https://app.slack.com/client/T029RQSE6/CBATURP1D) -[![license](https://img.shields.io/github/license/grpc-ecosystem/grpc-gateway?color=379c9c&style=flat-square)](https://github.com/grpc-ecosystem/grpc-gateway/blob/master/LICENSE.txt) -[![release](https://img.shields.io/github/v/release/grpc-ecosystem/grpc-gateway?color=379c9c&logoColor=ffffff&style=flat-square)](https://github.com/grpc-ecosystem/grpc-gateway/releases) -[![stars](https://img.shields.io/github/stars/grpc-ecosystem/grpc-gateway?color=379c9c&style=flat-square)](https://github.com/grpc-ecosystem/grpc-gateway/stargazers) +## About -The grpc-gateway is a plugin of the Google protocol buffers compiler +The gRPC-Gateway is a plugin of the Google protocol buffers compiler [protoc](https://github.com/protocolbuffers/protobuf). It reads protobuf service definitions and generates a reverse-proxy server which translates a RESTful HTTP API into gRPC. This server is generated according to the @@ -23,13 +29,11 @@ This helps you provide your APIs in both gRPC and RESTful style at the same time ## Testimonials > We use the gRPC-Gateway to serve millions of API requests per day, -> and have been since 2018, and through all of that, +> and have been since 2018 and through all of that, > we have never had any issues with it. > > _- William Mill, [Ad Hoc](http://adhocteam.us/)_ -## Check out our [documentation](https://grpc-ecosystem.github.io/grpc-gateway/)! - ## Background gRPC is great -- it generates API clients and server stubs in many programming @@ -46,7 +50,7 @@ that's needed to generate a reverse-proxy with this library. ## Installation -The grpc-gateway requires a local installation of the Google protocol buffers +The gRPC-Gateway requires a local installation of the Google protocol buffers compiler `protoc` v3.0.0 or above. Please install this via your local package manager or by downloading one of the releases from the official repository: @@ -151,7 +155,7 @@ Make sure that your `$GOBIN` is in your `$PATH`. 1. Using the default mapping - This requires no additional modification to the `.proto` file, but does require enabling a specific option when executing the plugin. + This requires no additional modification to the `.proto` file but does require enabling a specific option when executing the plugin. The `generate_unbound_methods` should be enabled. Here's what a `protoc` execution might look like with this option enabled: @@ -213,7 +217,7 @@ Make sure that your `$GOBIN` is in your `$PATH`. ``` 3. External configuration - If you do not want to (or cannot) modify the proto file for use with grpc-gateway you can + If you do not want to (or cannot) modify the proto file for use with gRPC-Gateway you can alternatively use an external [gRPC Service Configuration](https://cloud.google.com/endpoints/docs/grpc/grpc-service-config) file. [Check our documentation](https://grpc-ecosystem.github.io/grpc-gateway/docs/grpcapiconfiguration.html) @@ -292,15 +296,15 @@ Make sure that your `$GOBIN` is in your `$PATH`. This GopherCon UK 2019 presentation from our maintainer [@JohanBrandhorst](https://github.com/johanbrandhorst) provides a good intro to -using the grpc-gateway. It uses the following boilerplate repo as a base: +using the gRPC-Gateway. It uses the following boilerplate repo as a base: https://github.com/johanbrandhorst/grpc-gateway-boilerplate. [![gRPC-Gateway presentation](https://img.youtube.com/vi/Pq1paKC-fXk/0.jpg)](https://www.youtube.com/watch?v=Pq1paKC-fXk) ## Parameters and flags -During code generation with `protoc`, flags to grpc-gateway tools must be passed -through protoc using one of 2 patterns: +During code generation with `protoc`, flags to gRPC-Gateway tools must be passed +through `protoc` using one of 2 patterns: - as part of the `--_out` `protoc` parameter: `--_out=:` @@ -325,12 +329,12 @@ through protoc using one of 2 patterns: Golang import paths. They are compatible with [the parameters with the same names in `protoc-gen-go`](https://github.com/golang/protobuf#parameters). -In addition we also support the `request_context` parameter in order to use the +In addition, we also support the `request_context` parameter in order to use the `http.Request`'s Context (only for Go 1.7 and above). This parameter can be useful to pass the request-scoped context between the gateway and the gRPC service. `protoc-gen-grpc-gateway` also supports some more command line flags to control -logging. You can give these flags together with parameters above. Run +logging. You can give these flags together with the parameters above. Run `protoc-gen-grpc-gateway --help` for more details about the flags. Similarly, `protoc-gen-openapiv2` supports command-line flags to control OpenAPI @@ -342,9 +346,9 @@ files with options from [a_bit_of_everything.proto](examples/internal/proto/examplepb/a_bit_of_everything.proto) for examples. -## More Examples +## More examples -More examples are available under `examples` directory. +More examples are available under the `examples` directory. - `proto/examplepb/echo_service.proto`, `proto/examplepb/a_bit_of_everything.proto`, `proto/examplepb/unannotated_echo_service.proto`: service definition - `proto/examplepb/echo_service.pb.go`, `proto/examplepb/a_bit_of_everything.pb.go`, `proto/examplepb/unannotated_echo_service.pb.go`: [generated] stub of the service @@ -365,7 +369,7 @@ gRPC-gateway, and a gRPC server, see - Generating JSON API handlers. - Method parameters in the request body. - Method parameters in the request path. -- Method parameters in query string. +- Method parameters in the query string. - Enum fields in the path parameter (including repeated enum fields). - Mapping streaming APIs to newline-delimited JSON streams. - Mapping HTTP headers with `Grpc-Metadata-` prefix to gRPC metadata (prefixed with `grpcgateway-`) @@ -381,14 +385,14 @@ gRPC-gateway, and a gRPC server, see ### No plan to support -But patch is welcome. +But patches are welcome. - Method parameters in HTTP headers. - Handling trailer metadata. - Encoding request/response body in XML. - True bi-directional streaming. -# Mapping gRPC to HTTP +## Mapping gRPC to HTTP - [How gRPC error codes map to HTTP status codes in the response](https://github.com/grpc-ecosystem/grpc-gateway/blob/master/runtime/errors.go#L15). - HTTP request source IP is added as `X-Forwarded-For` gRPC request header. @@ -404,11 +408,11 @@ But patch is welcome. [jsonpb](https://pkg.go.dev/github.com/golang/protobuf/jsonpb) with `OrigName: true`. -# Contribution +## Contribution See [CONTRIBUTING.md](http://github.com/grpc-ecosystem/grpc-gateway/blob/master/CONTRIBUTING.md). -# License +## License -grpc-gateway is licensed under the BSD 3-Clause License. +gRPC-Gateway is licensed under the BSD 3-Clause License. See [LICENSE.txt](https://github.com/grpc-ecosystem/grpc-gateway/blob/master/LICENSE.txt) for more details. diff --git a/docs/_config.yml b/docs/_config.yml index fce681afb3f..b24108b0a14 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -77,7 +77,7 @@ gh_edit_link: true # show or hide edit this page link gh_edit_link_text: "Edit this page on GitHub" gh_edit_repository: "https://github.com/grpc-ecosystem/grpc-gateway" # the github URL for your repo gh_edit_branch: "master" # the branch that your docs is served from -# gh_edit_source: docs # the source that your files originate from +gh_edit_source: docs # the source that your files originate from gh_edit_view_mode: "tree" # "tree" or "edit" if you want the user to jump into the editor immediately # Color scheme currently only supports "dark", "light"/nil (default), or a custom scheme that you define @@ -85,9 +85,9 @@ color_scheme: nil # Disqus Comments # disqus: - # Leave shortname blank to disable comments site-wide. - # Enable comments for any post by adding `comments: true` to that post's YAML Front Matter. - # shortname: +# Leave shortname blank to disable comments site-wide. +# Enable comments for any post by adding `comments: true` to that post's YAML Front Matter. +# shortname: # Google Analytics Tracking # e.g, UA-1234567-89 diff --git a/docs/docs/contributing/contributing.md b/docs/docs/contributing/contributing.md deleted file mode 100644 index a529b436112..00000000000 --- a/docs/docs/contributing/contributing.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -layout: default -title: Getting Started -parent: Contributing ---- - -# How do I contribute - -See CONTRIBUTING in [the repo](https://github.com/grpc-ecosystem/grpc-gateway/blob/master/CONTRIBUTING.md). diff --git a/docs/docs/contributing/getting_started.md b/docs/docs/contributing/getting_started.md new file mode 100644 index 00000000000..c9bd862fddb --- /dev/null +++ b/docs/docs/contributing/getting_started.md @@ -0,0 +1,9 @@ +--- +layout: default +title: Getting Started +parent: Contributing +--- + +# How to contribute + +See CONTRIBUTING in [CONTRIBUTING.md](https://github.com/grpc-ecosystem/grpc-gateway/blob/master/CONTRIBUTING.md). diff --git a/docs/docs/tutorials/adding_annotations.md b/docs/docs/tutorials/adding_annotations.md index dbf1668edb2..2d6d80c2c49 100644 --- a/docs/docs/tutorials/adding_annotations.md +++ b/docs/docs/tutorials/adding_annotations.md @@ -1,19 +1,19 @@ --- layout: default -title: Adding the grpc-gateway annotations to an existing protobuf file +title: Adding gRPC-Gateway annotations to an existing proto file +nav_order: 4 parent: Tutorials -nav_order: 5 --- -# Adding the grpc-gateway annotations to an existing protobuf file +# Adding gRPC-Gateway annotations to an existing proto file -Now that we've got a working Go gRPC server, we need to add the grpc-gateway annotations. +Now that we've got a working Go gRPC server, we need to add the gRPC-Gateway annotations. The annotations define how gRPC services map to the JSON request and response. When using protocol buffers, each RPC must define the HTTP method and path using the `google.api.http` annotation. -So we will need to add the `google/api/http.proto` import to the proto file. We also need to add the HTTP->gRPC mapping we want. In this case, we're mapping `POST /v1/example/echo` to our `SayHello` rpc. +So we will need to add the `google/api/http.proto` import to the proto file. We also need to add the HTTP->gRPC mapping we want. In this case, we're mapping `POST /v1/example/echo` to our `SayHello` RPC. -```proto +```protobuf syntax = "proto3"; package helloworld; @@ -44,11 +44,11 @@ message HelloReply { See [a_bit_of_everything.proto](https://github.com/grpc-ecosystem/grpc-gateway/blob/master/examples/internal/proto/examplepb/a_bit_of_everything.proto) for examples of more annotations you can add to customize gateway behavior. -## Generating the grpc-gateway stubs +## Generating the gRPC-Gateway stubs -Now that we've got the grpc-gateway annotations added to the proto file, we need to use the grpc-gateway generator to generate the stubs. +Now that we've got the gRPC-Gateway annotations added to the proto file, we need to use the gRPC-Gateway generator to generate the stubs. -Before we can do that, we need to copy some dependencies into our protofile structure. Copy the `third_party/googleapis` folder from the grpc-gateway repository to your local protofile structure. It should look like this afterwards: +Before we can do that, we need to copy some dependencies into our proto file structure. Copy the `third_party/googleapis` folder from the gRPC-Gateway repository to your local proto file structure. It should look like this afterwards: ``` proto @@ -62,9 +62,9 @@ proto ### Using buf -We'll need to add the grpc-gateway generator to the generation configuration: +We'll need to add the gRPC-Gateway generator to the generation configuration: -```yml +```yaml version: v1beta1 plugins: - name: go @@ -86,9 +86,9 @@ $ buf generate It should produce a `*.gw.pb.go` file. -### Using protoc +### Using `protoc` -Now we need to add the grpc-gateway generator to the protoc invocation: +Now we need to add the gRPC-Gateway generator to the `protoc` invocation: ```sh $ protoc -I ./proto \ @@ -100,7 +100,7 @@ $ protoc -I ./proto \ This should generate a `*.gw.pb.go` file. -We also need to add and serve the gRPC-gateway mux in our `main.go` file. +We also need to add and serve the gRPC-Gateway mux in our `main.go` file. ```go package main diff --git a/docs/docs/tutorials/creating_main.go.md b/docs/docs/tutorials/creating_main.go.md index 669dfac31e5..6232b05ea8b 100644 --- a/docs/docs/tutorials/creating_main.go.md +++ b/docs/docs/tutorials/creating_main.go.md @@ -1,8 +1,8 @@ --- layout: default title: Creating main.go +nav_order: 3 parent: Tutorials -nav_order: 4 --- # Creating main.go diff --git a/docs/docs/tutorials/generating_stubs/index.md b/docs/docs/tutorials/generating_stubs/index.md index 172467df30f..ec873a6a5d3 100644 --- a/docs/docs/tutorials/generating_stubs/index.md +++ b/docs/docs/tutorials/generating_stubs/index.md @@ -2,7 +2,7 @@ layout: default title: Generating stubs parent: Tutorials -nav_order: 3 +nav_order: 2 has_children: true --- diff --git a/docs/docs/tutorials/generating_stubs/using_buf.md b/docs/docs/tutorials/generating_stubs/using_buf.md index 392c5470ca2..953cfcb76f4 100644 --- a/docs/docs/tutorials/generating_stubs/using_buf.md +++ b/docs/docs/tutorials/generating_stubs/using_buf.md @@ -1,9 +1,9 @@ --- layout: default title: Generating stubs using buf +nav_order: 0 parent: Generating stubs grand_parent: Tutorials -nav_order: 1 --- # Generating stubs using buf @@ -16,7 +16,7 @@ All Buf operations that use your local `.proto` files as input rely on a valid b The following is an example of a valid configuration, assuming you have your `.proto` files rooted in the `proto` folder relative to the root of your repository. -```yml +```yaml version: v1beta1 build: roots: @@ -25,7 +25,7 @@ build: To generate type and gRPC stubs for Go, create the file `buf.gen.yaml` at the root of the repository: -```yml +```yaml version: v1beta1 plugins: - name: go diff --git a/docs/docs/tutorials/generating_stubs/using_protoc.md b/docs/docs/tutorials/generating_stubs/using_protoc.md index 240fe0e4689..b72eeb1120d 100644 --- a/docs/docs/tutorials/generating_stubs/using_protoc.md +++ b/docs/docs/tutorials/generating_stubs/using_protoc.md @@ -1,9 +1,9 @@ --- layout: default title: Generating stubs using protoc +nav_order: 1 parent: Generating stubs grand_parent: Tutorials -nav_order: 2 --- # Generating stubs using protoc diff --git a/docs/docs/tutorials/index.md b/docs/docs/tutorials/index.md index af5856ec9e3..ad3f51c5163 100644 --- a/docs/docs/tutorials/index.md +++ b/docs/docs/tutorials/index.md @@ -1,6 +1,6 @@ --- layout: default title: Tutorials -nav_order: 7 +nav_order: 6 has_children: true --- diff --git a/docs/docs/tutorials/introduction.md b/docs/docs/tutorials/introduction.md index 4d838329187..d179c94a22d 100644 --- a/docs/docs/tutorials/introduction.md +++ b/docs/docs/tutorials/introduction.md @@ -1,8 +1,8 @@ --- layout: default title: Introduction to the gRPC-Gateway +nav_order: 0 parent: Tutorials -nav_order: 1 --- # Introduction to the gRPC-Gateway @@ -13,11 +13,13 @@ So is there any way to code just once, but provide APIs in both gRPC and HTTP/JS The answer is Yes. -The grpc-gateway is a plugin of the Google protocol buffers compiler [protoc](https://github.com/protocolbuffers/protobuf). It reads protobuf service definitions and generates a reverse-proxy server which translates a RESTful HTTP API into gRPC. This server is generated according to the [`google.api.http`](https://github.com/googleapis/googleapis/blob/master/google/api/http.proto#L46) annotations in your service definitions. +The gRPC-Gateway is a plugin of the Google protocol buffers compiler [protoc](https://github.com/protocolbuffers/protobuf). It reads protobuf service definitions and generates a reverse-proxy server which translates a RESTful HTTP API into gRPC. This server is generated according to the [`google.api.http`](https://github.com/googleapis/googleapis/blob/master/google/api/http.proto#L46) annotations in your service definitions. This helps you provide your APIs in both gRPC and HTTP/JSON format at the same time. -![architecture introduction diagram](https://docs.google.com/drawings/d/12hp4CPqrNPFhattL_cIoJptFvlAqm5wLQ0ggqI5mkCg/pub?w=749&h=370) +
+ +
## Prerequisites @@ -33,7 +35,8 @@ $ go get google.golang.org/protobuf/cmd/protoc-gen-go $ go get google.golang.org/grpc/cmd/protoc-gen-go-grpc ``` -This installs the protoc generator plugins we need to generate the stubs. Make sure to add `$GOPATH/bin` to your `$PATH` so that executables installed via `go get` are available on your `$PATH`. +This installs the `protoc` generator plugins we need to generate the stubs. Make sure to add `$GOPATH/bin` to your `$PATH` so that executables installed via `go get` are available on your `$PATH`. + We will be working in a new module for this tutorial, so go ahead and create that in a folder of your choosing now: ### Creating go.mod file diff --git a/docs/docs/tutorials/learn_more.md b/docs/docs/tutorials/learn_more.md index c912c7c1ccc..b9d950da28e 100644 --- a/docs/docs/tutorials/learn_more.md +++ b/docs/docs/tutorials/learn_more.md @@ -1,20 +1,20 @@ --- layout: default title: Learn More +nav_order: 5 parent: Tutorials -nav_order: 6 --- # Learn More ## How it works -When the HTTP request arrives at the gRPC-gateway, it parses the JSON data into a protobuf message. It then makes a normal Go gRPC client request using the parsed protobuf message. The Go gRPC client encodes the protobuf structure into the protobuf binary format and sends it to the gRPC server. The gRPC Server handles the request and returns the response in the protobuf binary format. The Go gRPC client parses it into a protobuf message and returns it to the gRPC-gateway, which encodes the protobuf message to JSON and returns it to the original client. +When the HTTP request arrives at the gRPC-Gateway, it parses the JSON data into a protobuf message. It then makes a normal Go gRPC client request using the parsed protobuf message. The Go gRPC client encodes the protobuf structure into the protobuf binary format and sends it to the gRPC server. The gRPC Server handles the request and returns the response in the protobuf binary format. The Go gRPC client parses it into a protobuf message and returns it to the gRPC-Gateway, which encodes the protobuf message to JSON and returns it to the original client. ## google.api.http -Read more about `google.api.http` on [https://github.com/googleapis/googleapis/blob/master/google/api/http.proto](https://github.com/googleapis/googleapis/blob/master/google/api/http.proto) +Read more about `google.api.http` in [the source file documentation](https://github.com/googleapis/googleapis/blob/master/google/api/http.proto). ## HTTP and gRPC Transcoding -Read more about HTTP and gRPC Transcoding on [https://google.aip.dev/127](https://google.aip.dev/127) +Read more about HTTP and gRPC Transcoding on [AIP 127](https://google.aip.dev/127). diff --git a/docs/docs/tutorials/simple_hello_world.md b/docs/docs/tutorials/simple_hello_world.md index 7347a534687..71251833251 100644 --- a/docs/docs/tutorials/simple_hello_world.md +++ b/docs/docs/tutorials/simple_hello_world.md @@ -1,8 +1,8 @@ --- layout: default title: Creating a simple hello world with gRPC +nav_order: 1 parent: Tutorials -nav_order: 2 --- # Creating a simple hello world with gRPC @@ -15,7 +15,7 @@ Before we create a gRPC service, we should create a proto file to define what we The gRPC service is defined using [Google Protocol Buffers](https://developers.google.com/protocol-buffers). To learn more about how to define a service in a `.proto` file see their [Basics tutorial](https://grpc.io/docs/languages/go/basics/). For now, all you need to know is that both the server and the client stub have a `SayHello()` RPC method that takes a `HelloRequest` parameter from the client and returns a `HelloReply` from the server, and that the method is defined like this: -```proto +```protobuf syntax = "proto3"; package helloworld; diff --git a/docs/index.md b/docs/index.md index 5c70838822e..3bf0923687f 100644 --- a/docs/index.md +++ b/docs/index.md @@ -21,14 +21,14 @@ This server is generated according to [custom options](https://cloud.google.com/ ## Getting started -[![circleci](https://img.shields.io/circleci/build/github/grpc-ecosystem/grpc-gateway?color=379c9c&logo=circleci&logoColor=ffffff&style=flat-square)](https://circleci.com/gh/grpc-ecosystem/grpc-gateway) -[![codecov](https://img.shields.io/codecov/c/github/grpc-ecosystem/grpc-gateway?color=379c9c&logo=codecov&logoColor=ffffff&style=flat-square)](https://codecov.io/gh/grpc-ecosystem/grpc-gateway) -[![slack](https://img.shields.io/badge/slack-grpc--gateway-379c9c?logo=slack&logoColor=ffffff&style=flat-square)](https://app.slack.com/client/T029RQSE6/CBATURP1D) -[![license](https://img.shields.io/github/license/grpc-ecosystem/grpc-gateway?color=379c9c&style=flat-square)](https://github.com/grpc-ecosystem/grpc-gateway/blob/master/LICENSE.txt) -[![release](https://img.shields.io/github/v/release/grpc-ecosystem/grpc-gateway?color=379c9c&logoColor=ffffff&style=flat-square)](https://github.com/grpc-ecosystem/grpc-gateway/releases) -[![stars](https://img.shields.io/github/stars/grpc-ecosystem/grpc-gateway?color=379c9c&style=flat-square)](https://github.com/grpc-ecosystem/grpc-gateway/stargazers) - -grpc-gateway is a plugin of [protoc](https://github.com/protocolbuffers/protobuf). + + + + + + + +gRPC-Gateway is a plugin of [protoc](https://github.com/protocolbuffers/protobuf). It reads a [gRPC](https://grpc.io) service definition, and generates a reverse-proxy server which translates a RESTful JSON API into gRPC. This server is generated according to [custom options](https://cloud.google.com/service-infrastructure/docs/service-management/reference/rpc/google.api#http) in your gRPC definition. @@ -47,10 +47,10 @@ See [CONTRIBUTING.md](http://github.com/grpc-ecosystem/grpc-gateway/blob/master/ ## License -grpc-gateway is licensed under the BSD 3-Clause License. +gRPC-Gateway is licensed under the BSD 3-Clause License. See [LICENSE.txt](https://github.com/grpc-ecosystem/grpc-gateway/blob/master/LICENSE.txt) for more details. -#### Thank you to the contributors of gRPC-Gateway! +### Thank you to the contributors of gRPC-Gateway
    {% for contributor in site.github.contributors %}