From 5bac8f1d64c5b37a5ad14e10380c91caef5c6e92 Mon Sep 17 00:00:00 2001 From: Eric Hauser Date: Sat, 14 Nov 2020 03:46:55 -0800 Subject: [PATCH] reorganize docs; add page for customizing gateway output (#1822) --- docs/docs/contributing/contributing.md | 9 + docs/docs/contributing/index.md | 6 + .../docs/{ => contributing}/season_of_docs.md | 2 +- docs/docs/{ => development}/cygwin.md | 3 +- docs/docs/development/index.md | 6 + docs/docs/{ => development}/v2-migration.md | 3 +- docs/docs/mapping/customizingopenapioutput.md | 203 ++++++++++++++++++ .../{ => mapping}/customizingyourgateway.md | 3 +- docs/docs/{ => mapping}/examples.md | 3 +- .../{ => mapping}/grpcapiconfiguration.md | 3 +- docs/docs/{ => mapping}/httpbody.md | 3 +- docs/docs/mapping/index.md | 6 + docs/docs/{ => mapping}/patch.md | 3 +- docs/docs/{ => operations}/aws.md | 5 +- docs/docs/{ => operations}/healthcheck.md | 3 +- docs/docs/operations/index.md | 6 + docs/docs/{ => operations}/inject_router.md | 3 +- docs/docs/{ => operations}/tracing.md | 3 +- docs/docs/{ => overview}/background.md | 2 +- docs/docs/overview/index.md | 6 + docs/docs/{ => overview}/usage.md | 2 +- docs/docs/usegotemplates.md | 112 ---------- docs/index.md | 2 +- 23 files changed, 269 insertions(+), 128 deletions(-) create mode 100644 docs/docs/contributing/contributing.md create mode 100644 docs/docs/contributing/index.md rename docs/docs/{ => contributing}/season_of_docs.md (99%) rename docs/docs/{ => development}/cygwin.md (99%) create mode 100644 docs/docs/development/index.md rename docs/docs/{ => development}/v2-migration.md (99%) create mode 100644 docs/docs/mapping/customizingopenapioutput.md rename docs/docs/{ => mapping}/customizingyourgateway.md (99%) rename docs/docs/{ => mapping}/examples.md (98%) rename docs/docs/{ => mapping}/grpcapiconfiguration.md (99%) rename docs/docs/{ => mapping}/httpbody.md (98%) create mode 100644 docs/docs/mapping/index.md rename docs/docs/{ => mapping}/patch.md (99%) rename docs/docs/{ => operations}/aws.md (93%) rename docs/docs/{ => operations}/healthcheck.md (97%) create mode 100644 docs/docs/operations/index.md rename docs/docs/{ => operations}/inject_router.md (97%) rename docs/docs/{ => operations}/tracing.md (99%) rename docs/docs/{ => overview}/background.md (97%) create mode 100644 docs/docs/overview/index.md rename docs/docs/{ => overview}/usage.md (89%) delete mode 100644 docs/docs/usegotemplates.md diff --git a/docs/docs/contributing/contributing.md b/docs/docs/contributing/contributing.md new file mode 100644 index 00000000000..a529b436112 --- /dev/null +++ b/docs/docs/contributing/contributing.md @@ -0,0 +1,9 @@ +--- +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/index.md b/docs/docs/contributing/index.md new file mode 100644 index 00000000000..4241bd25bc4 --- /dev/null +++ b/docs/docs/contributing/index.md @@ -0,0 +1,6 @@ +--- +layout: default +title: Contributing +nav_order: 5 +has_children: true +--- diff --git a/docs/docs/season_of_docs.md b/docs/docs/contributing/season_of_docs.md similarity index 99% rename from docs/docs/season_of_docs.md rename to docs/docs/contributing/season_of_docs.md index 6515d7a8078..f116a513c94 100644 --- a/docs/docs/season_of_docs.md +++ b/docs/docs/contributing/season_of_docs.md @@ -1,7 +1,7 @@ --- layout: default title: 2020 Season of Docs -nav_order: 13 +parent: Contributing --- # 2020 Season of Docs diff --git a/docs/docs/cygwin.md b/docs/docs/development/cygwin.md similarity index 99% rename from docs/docs/cygwin.md rename to docs/docs/development/cygwin.md index 697fe7ba832..bf351c84772 100644 --- a/docs/docs/cygwin.md +++ b/docs/docs/development/cygwin.md @@ -1,7 +1,8 @@ --- layout: default title: Installation for Cygwin -nav_order: 5 +parent: Developing +nav_order: 2 --- # Installation for Cygwin diff --git a/docs/docs/development/index.md b/docs/docs/development/index.md new file mode 100644 index 00000000000..1af2329bca5 --- /dev/null +++ b/docs/docs/development/index.md @@ -0,0 +1,6 @@ +--- +layout: default +title: Developing +nav_order: 4 +has_children: true +--- diff --git a/docs/docs/v2-migration.md b/docs/docs/development/v2-migration.md similarity index 99% rename from docs/docs/v2-migration.md rename to docs/docs/development/v2-migration.md index 22e704c91c0..893a7dca126 100644 --- a/docs/docs/v2-migration.md +++ b/docs/docs/development/v2-migration.md @@ -1,7 +1,8 @@ --- layout: default title: gRPC-Gateway v2 migration guide -nav_order: 17 +parent: Developing +nav_order: 1 --- # gRPC-Gateway v2 migration guide diff --git a/docs/docs/mapping/customizingopenapioutput.md b/docs/docs/mapping/customizingopenapioutput.md new file mode 100644 index 00000000000..1650c62182f --- /dev/null +++ b/docs/docs/mapping/customizingopenapioutput.md @@ -0,0 +1,203 @@ +--- +layout: default +title: Customizing OpenAPI Ouptut +parent: Mapping +nav_order: 5 +--- + +{% raw %} + +# In proto comments + +You can provide comments directly in your Protocol Buffer defintions and they will be translated into comments in the generated OpenAPI definitions: + +```protobuf +message MyMessage { + // This comment will end up direcly in your Open API definition + string uuid = 1 [(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {description: "The UUID field."}]; +} +``` + +# Using proto options + +You can define options on your Protocol Buffer services, operations, messages, and field definitions to customize your Open API output. For instance, to customize the [OpenAPI Schema Object](https://swagger.io/specification/v2/#schemaObject) for messages and fields: + +```protobuf +import "protoc-gen-openapiv2/options/annotations.proto"; + +message ABitOfEverything { + option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_schema) = { + json_schema: { + title: "A bit of everything" + description: "Intentionaly complicated message type to cover many features of Protobuf." + required: ["uuid", "int64_value", "double_value"] + } + external_docs: { + url: "https://github.com/grpc-ecosystem/grpc-gateway"; + description: "Find out more about ABitOfEverything"; + } + example: "{\"uuid\": \"0cf361e1-4b44-483d-a159-54dabdf7e814\"}" + }; + + string uuid = 1 [(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {description: "The UUID field."}]; +} +``` + +Operations can also be customized: + +```protobuf +service ABitOfEverythingService { + rpc Delete(grpc.gateway.examples.internal.proto.sub2.IdMessage) returns (google.protobuf.Empty) { + option (google.api.http) = { + delete: "/v1/example/a_bit_of_everything/{uuid}" + }; + option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { + security: { + security_requirement: { + key: "ApiKeyAuth"; + value: {} + } + security_requirement: { + key: "OAuth2"; + value: { + scope: "read"; + scope: "write"; + } + } + } + extensions: { + key: "x-irreversible"; + value { + bool_value: true; + } + } + }; + } +} +``` + +Please see this [example](https://github.com/grpc-ecosystem/grpc-gateway/blob/master/examples/internal/proto/examplepb/a_bit_of_everything.proto) for examples of the options being used. + +# Using google.api.field_behavior + +Google provides an [field option](https://github.com/googleapis/googleapis/blob/master/google/api/field_behavior.proto) for defining the behavior of fields that is also supported: + +```protobuf +import "google/api/field_behavior.proto"; + +message MyMessage { + string a_required_field = 1 [(google.api.field_behavior) = REQUIRED]; +} +``` + +The following options are used in the Open API output: + +* `REQUIRED` - marks a field as required +* `OUTPUT_ONLY` - marks a field as readonly + +Google defines a couple other options - `OPTIONAL`, `IMMUTABLE`, `INPUT_ONLY` - that are not currently used. `OPTIONAL` support is currently under discussion in [this issue](https://github.com/grpc-ec system/grpc-gateway/issues/669). For `IMMUTABLE` and `INPUT_ONLY` fields, there is an [open issue](https://github.com/OAI/OpenAPI-Specification/issues/1497) in the Open API specification for adding functionality for write once or immutable fields to the spec. + +# Using go templates in protofile comments + +Use [Go templates](https://golang.org/pkg/text/template/) +in your protofile comments to allow more advanced documentation such +as: + +- Documentation about fields in the proto objects. +- Import the content of external files (such as + [Markdown](https://en.wikipedia.org/wiki/Markdown)). + +## How to use it + +By default this function is turned off, so if you want to use it you +have to add the `use_go_templates` option: + +```shell +--openapiv2_out . --openapiv2_opt use_go_templates=true +``` + +or: + +```shell +--openapiv2_out=use_go_templates=true:. +``` + +### Example script + +Example of a bash script with the `use_go_templates` flag set to true: + +```shell +$ protoc -I. \ + --go_out . --go-grpc_out . \ + --grpc-gateway_out . --grpc-gateway_opt logtostderr=true \ + --openapiv2_out . \ + --openapiv2_opt logtostderr=true \ + --openapiv2_opt use_go_templates=true \ + path/to/my/proto/v1/myproto.proto +``` + +### Example proto file + +Example of a protofile with Go templates. This proto file imports documentation from another file, `tables.md`: + +```protobuf +service LoginService { + // Login + // + // {{.MethodDescriptorProto.Name}} is a call with the method(s) {{$first := true}}{{range .Bindings}}{{if $first}}{{$first = false}}{{else}}, {{end}}{{.HTTPMethod}}{{end}} within the "{{.Service.Name}}" service. + // It takes in "{{.RequestType.Name}}" and returns a "{{.ResponseType.Name}}". + // + // {{import "tables.md"}} + rpc Login (LoginRequest) returns (LoginReply) { + option (google.api.http) = { + post: "/v1/example/login" + body: "*" + }; + } +} + +message LoginRequest { + // The entered username + string username = 1; + // The entered password + string password = 2; +} + +message LoginReply { + // Whether you have access or not + bool access = 1; +} +``` + +The content of `tables.md`: + +```markdown +## {{.RequestType.Name}} +| Field ID | Name | Type | Description | +| ----------- | --------- | --------------------------------------------------------- | ---------------------------- | {{range .RequestType.Fields}} +| {{.Number}} | {{.Name}} | {{if eq .Label.String "LABEL_REPEATED"}}[]{{end}}{{.Type}} | {{fieldcomments .Message .}} | {{end}} + +## {{.ResponseType.Name}} +| Field ID | Name | Type | Description | +| ----------- | --------- | ---------------------------------------------------------- | ---------------------------- | {{range .ResponseType.Fields}} +| {{.Number}} | {{.Name}} | {{if eq .Label.String "LABEL_REPEATED"}}[]{{end}}{{.Type}} | {{fieldcomments .Message .}} | {{end}} +``` + +## OpenAPI output + +### SwaggerUI + +This is how the OpenAPI file would be rendered in [Swagger UI](https://swagger.io/tools/swagger-ui/) + +![Screenshot OpenAPI file in SwaggerUI](../assets/images/gotemplates/swaggerui.png) + +### Postman + +This is how the OpenAPI file would be rendered in [Postman](https://www.getpostman.com/) + +![Screenshot OpenAPI file in Postman](../assets/images/gotemplates/postman.png) + +For a more detailed example of a protofile that has Go templates enabled, +[see the examples](https://github.com/grpc-ecosystem/grpc-gateway/blob/master/examples/internal/proto/examplepb/use_go_template.proto). + +{% endraw %} diff --git a/docs/docs/customizingyourgateway.md b/docs/docs/mapping/customizingyourgateway.md similarity index 99% rename from docs/docs/customizingyourgateway.md rename to docs/docs/mapping/customizingyourgateway.md index f1f31d722ab..a4f4e4732d6 100644 --- a/docs/docs/customizingyourgateway.md +++ b/docs/docs/mapping/customizingyourgateway.md @@ -1,7 +1,8 @@ --- layout: default title: Customizing your gateway -nav_order: 4 +parent: Mapping +nav_order: 10 --- # Customizing your gateway diff --git a/docs/docs/examples.md b/docs/docs/mapping/examples.md similarity index 98% rename from docs/docs/examples.md rename to docs/docs/mapping/examples.md index cfa70cbb066..3528336c5fa 100644 --- a/docs/docs/examples.md +++ b/docs/docs/mapping/examples.md @@ -1,7 +1,8 @@ --- layout: default title: Examples -nav_order: 6 +parent: Mapping +nav_order: 1 --- # Examples diff --git a/docs/docs/grpcapiconfiguration.md b/docs/docs/mapping/grpcapiconfiguration.md similarity index 99% rename from docs/docs/grpcapiconfiguration.md rename to docs/docs/mapping/grpcapiconfiguration.md index 2195a7cb995..b6a33f329f3 100644 --- a/docs/docs/grpcapiconfiguration.md +++ b/docs/docs/mapping/grpcapiconfiguration.md @@ -1,7 +1,8 @@ --- layout: default title: gRPC API Configuration -nav_order: 8 +parent: Mapping +nav_order: 4 --- # gRPC API Configuration diff --git a/docs/docs/httpbody.md b/docs/docs/mapping/httpbody.md similarity index 98% rename from docs/docs/httpbody.md rename to docs/docs/mapping/httpbody.md index c948f185d1d..409ad9a4b68 100644 --- a/docs/docs/httpbody.md +++ b/docs/docs/mapping/httpbody.md @@ -1,7 +1,8 @@ --- layout: default title: HttpBody messages -nav_order: 10 +parent: Mapping +nav_order: 2 --- # HttpBody messages diff --git a/docs/docs/mapping/index.md b/docs/docs/mapping/index.md new file mode 100644 index 00000000000..88e1a943f5d --- /dev/null +++ b/docs/docs/mapping/index.md @@ -0,0 +1,6 @@ +--- +layout: default +title: Mapping +nav_order: 2 +has_children: true +--- diff --git a/docs/docs/patch.md b/docs/docs/mapping/patch.md similarity index 99% rename from docs/docs/patch.md rename to docs/docs/mapping/patch.md index 7a880e60c1d..77b5e805fd8 100644 --- a/docs/docs/patch.md +++ b/docs/docs/mapping/patch.md @@ -1,7 +1,8 @@ --- layout: default title: Patch Feature -nav_order: 12 +parent: Mapping +nav_order: 3 --- # Patch Feature diff --git a/docs/docs/aws.md b/docs/docs/operations/aws.md similarity index 93% rename from docs/docs/aws.md rename to docs/docs/operations/aws.md index 8771304558e..615be257c5f 100644 --- a/docs/docs/aws.md +++ b/docs/docs/operations/aws.md @@ -1,7 +1,8 @@ --- layout: default -title: AWS -nav_order: 2 +title: AWS Gateway Integration +parent: Operations +nav_order: 5 --- # AWS diff --git a/docs/docs/healthcheck.md b/docs/docs/operations/healthcheck.md similarity index 97% rename from docs/docs/healthcheck.md rename to docs/docs/operations/healthcheck.md index 8dea546298f..15e204a49fc 100644 --- a/docs/docs/healthcheck.md +++ b/docs/docs/operations/healthcheck.md @@ -1,7 +1,8 @@ --- layout: default title: Health Check -nav_order: 9 +parent: Operations +nav_order: 3 --- # Health check diff --git a/docs/docs/operations/index.md b/docs/docs/operations/index.md new file mode 100644 index 00000000000..9ec5ab4b6fe --- /dev/null +++ b/docs/docs/operations/index.md @@ -0,0 +1,6 @@ +--- +layout: default +title: Operations +nav_order: 3 +has_children: true +--- diff --git a/docs/docs/inject_router.md b/docs/docs/operations/inject_router.md similarity index 97% rename from docs/docs/inject_router.md rename to docs/docs/operations/inject_router.md index cc9532acd6c..e6f6ec1dfb0 100644 --- a/docs/docs/inject_router.md +++ b/docs/docs/operations/inject_router.md @@ -1,7 +1,8 @@ --- layout: default title: Adding custom routes to the mux -nav_order: 11 +parent: Operations +nav_order: 2 --- # Adding custom routes to the mux diff --git a/docs/docs/tracing.md b/docs/docs/operations/tracing.md similarity index 99% rename from docs/docs/tracing.md rename to docs/docs/operations/tracing.md index 58183065dac..c695d76b9cd 100644 --- a/docs/docs/tracing.md +++ b/docs/docs/operations/tracing.md @@ -1,7 +1,8 @@ --- layout: default title: Tracing -nav_order: 14 +parent: Operations +nav_order: 4 --- # Tracing diff --git a/docs/docs/background.md b/docs/docs/overview/background.md similarity index 97% rename from docs/docs/background.md rename to docs/docs/overview/background.md index 6a066610f7a..3e23722ebf1 100644 --- a/docs/docs/background.md +++ b/docs/docs/overview/background.md @@ -1,7 +1,7 @@ --- layout: default title: Background -nav_order: 3 +parent: Overview --- # Background diff --git a/docs/docs/overview/index.md b/docs/docs/overview/index.md new file mode 100644 index 00000000000..481fbe842c2 --- /dev/null +++ b/docs/docs/overview/index.md @@ -0,0 +1,6 @@ +--- +layout: default +title: Overview +nav_order: 1 +has_children: true +--- diff --git a/docs/docs/usage.md b/docs/docs/overview/usage.md similarity index 89% rename from docs/docs/usage.md rename to docs/docs/overview/usage.md index 4d63ed62016..473f3656cf7 100644 --- a/docs/docs/usage.md +++ b/docs/docs/overview/usage.md @@ -1,7 +1,7 @@ --- layout: default title: How do I use this? -nav_order: 15 +parent: Overview --- # How do I use this? diff --git a/docs/docs/usegotemplates.md b/docs/docs/usegotemplates.md deleted file mode 100644 index 009f082a2af..00000000000 --- a/docs/docs/usegotemplates.md +++ /dev/null @@ -1,112 +0,0 @@ ---- -layout: default -title: Use go templates in protofile comments -nav_order: 16 ---- - -{% raw %} - -# Use go templates in protofile comments - -Use [Go templates](https://golang.org/pkg/text/template/) -in your protofile comments to allow more advanced documentation such -as: - -- Documentation about fields in the proto objects. -- Import the content of external files (such as - [Markdown](https://en.wikipedia.org/wiki/Markdown)). - -## How to use it - -By default this function is turned off, so if you want to use it you -have to add the `use_go_templates` option: - -```shell ---openapiv2_out . --openapiv2_opt use_go_templates=true -``` - -or: - -```shell ---openapiv2_out=use_go_templates=true:. -``` - -### Example script - -Example of a bash script with the `use_go_templates` flag set to true: - -```shell -$ protoc -I. \ - --go_out . --go-grpc_out . \ - --grpc-gateway_out . --grpc-gateway_opt logtostderr=true \ - --openapiv2_out . \ - --openapiv2_opt logtostderr=true \ - --openapiv2_opt use_go_templates=true \ - path/to/my/proto/v1/myproto.proto -``` - -### Example proto file - -Example of a protofile with Go templates. This proto file imports documentation from another file, `tables.md`: - -```protobuf -service LoginService { - // Login - // - // {{.MethodDescriptorProto.Name}} is a call with the method(s) {{$first := true}}{{range .Bindings}}{{if $first}}{{$first = false}}{{else}}, {{end}}{{.HTTPMethod}}{{end}} within the "{{.Service.Name}}" service. - // It takes in "{{.RequestType.Name}}" and returns a "{{.ResponseType.Name}}". - // - // {{import "tables.md"}} - rpc Login (LoginRequest) returns (LoginReply) { - option (google.api.http) = { - post: "/v1/example/login" - body: "*" - }; - } -} - -message LoginRequest { - // The entered username - string username = 1; - // The entered password - string password = 2; -} - -message LoginReply { - // Whether you have access or not - bool access = 1; -} -``` - -The content of `tables.md`: - -```markdown -## {{.RequestType.Name}} -| Field ID | Name | Type | Description | -| ----------- | --------- | --------------------------------------------------------- | ---------------------------- | {{range .RequestType.Fields}} -| {{.Number}} | {{.Name}} | {{if eq .Label.String "LABEL_REPEATED"}}[]{{end}}{{.Type}} | {{fieldcomments .Message .}} | {{end}} - -## {{.ResponseType.Name}} -| Field ID | Name | Type | Description | -| ----------- | --------- | ---------------------------------------------------------- | ---------------------------- | {{range .ResponseType.Fields}} -| {{.Number}} | {{.Name}} | {{if eq .Label.String "LABEL_REPEATED"}}[]{{end}}{{.Type}} | {{fieldcomments .Message .}} | {{end}} -``` - -## OpenAPI output - -### SwaggerUI - -This is how the OpenAPI file would be rendered in [Swagger UI](https://swagger.io/tools/swagger-ui/) - -![Screenshot OpenAPI file in SwaggerUI](../assets/images/gotemplates/swaggerui.png) - -### Postman - -This is how the OpenAPI file would be rendered in [Postman](https://www.getpostman.com/) - -![Screenshot OpenAPI file in Postman](../assets/images/gotemplates/postman.png) - -For a more detailed example of a protofile that has Go templates enabled, -[see the examples](https://github.com/grpc-ecosystem/grpc-gateway/blob/master/examples/internal/proto/examplepb/use_go_template.proto). - -{% endraw %} diff --git a/docs/index.md b/docs/index.md index 1eb66f086fd..397dd66dedb 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,7 +1,7 @@ --- layout: default title: gRPC-Gateway -nav_order: 1 +nav_order: 0 description: "Documentation site for the gRPC-Gateway" permalink: / ---