|
| 1 | +| Title | Category | |
| 2 | +| -------------------------------------- | ------------- | |
| 3 | +| Use go templates in protofile comments | Documentation | |
| 4 | + |
| 5 | +# Use go templates in protofile comments |
| 6 | + |
| 7 | +Use [Go templates](https://golang.org/pkg/text/template/ "Package template") in your protofile comments to allow more advanced documentation such as: |
| 8 | +* Documentation about fields in the proto objects. |
| 9 | +* Import the content of external files (such as [Markdown](https://en.wikipedia.org/wiki/Markdown "Markdown Github")). |
| 10 | + |
| 11 | +## How to use it |
| 12 | + |
| 13 | +By default this function is turned off, so if you want to use it you have to set the `use_go_templates` flag to true inside of the `swagger_out` flag. |
| 14 | +```bash |
| 15 | +--swagger_out=use_go_templates=true:. |
| 16 | +``` |
| 17 | + |
| 18 | +### Example script |
| 19 | + |
| 20 | +Example of a bash script with the `use_go_templates` flag set to true: |
| 21 | + |
| 22 | +```bash |
| 23 | +protoc -I/usr/local/include -I. \ |
| 24 | + -I$GOPATH/src \ |
| 25 | + -I$GOPATH/src/github.com/grpc-ecosystem/grpc-gateway/third_party/googleapis \ |
| 26 | + -I$GOPATH/src/github.com/grpc-ecosystem/grpc-gateway \ |
| 27 | + --go_out=plugins=grpc:. \ |
| 28 | + --grpc-gateway_out=logtostderr=true:. \ |
| 29 | + --swagger_out=logtostderr=true,use_go_templates=true:. \ |
| 30 | + *.proto |
| 31 | +``` |
| 32 | + |
| 33 | +### Example proto file |
| 34 | + |
| 35 | +Example of a protofile with Go templates. This proto file imports documentation from another file, `tables.md`: |
| 36 | +```protobuf |
| 37 | +service LoginService { |
| 38 | + // Login |
| 39 | + // |
| 40 | + // {{.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. |
| 41 | + // It takes in "{{.RequestType.Name}}" and returns a "{{.ResponseType.Name}}". |
| 42 | + // |
| 43 | + // {{import "tables.md"}} |
| 44 | + rpc Login (LoginRequest) returns (LoginReply) { |
| 45 | + option (google.api.http) = { |
| 46 | + post: "/v1/example/login" |
| 47 | + body: "*" |
| 48 | + }; |
| 49 | + } |
| 50 | +} |
| 51 | +
|
| 52 | +message LoginRequest { |
| 53 | + // The entered username |
| 54 | + string username = 1; |
| 55 | + // The entered password |
| 56 | + string password = 2; |
| 57 | +} |
| 58 | +
|
| 59 | +message LoginReply { |
| 60 | + // Whether you have access or not |
| 61 | + bool access = 1; |
| 62 | +} |
| 63 | +``` |
| 64 | + |
| 65 | +The content of `tables.md`: |
| 66 | + |
| 67 | +```markdown |
| 68 | +## {{.RequestType.Name}} |
| 69 | +| Field ID | Name | Type | Description | |
| 70 | +| ----------- | --------- | --------------------------------------------------------- | ---------------------------- | {{range .RequestType.Fields}} |
| 71 | +| {{.Number}} | {{.Name}} | {{if eq .Label.String "LABEL_REPEATED"}}[]{{end}}{{.Type}} | {{fieldcomments .Message .}} | {{end}} |
| 72 | + |
| 73 | +## {{.ResponseType.Name}} |
| 74 | +| Field ID | Name | Type | Description | |
| 75 | +| ----------- | --------- | ---------------------------------------------------------- | ---------------------------- | {{range .ResponseType.Fields}} |
| 76 | +| {{.Number}} | {{.Name}} | {{if eq .Label.String "LABEL_REPEATED"}}[]{{end}}{{.Type}} | {{fieldcomments .Message .}} | {{end}} |
| 77 | +``` |
| 78 | + |
| 79 | +## Swagger output |
| 80 | + |
| 81 | +### SwaggerUI |
| 82 | + |
| 83 | +This is how the swagger file would be rendered in [SwaggerUI](https://swagger.io/tools/swagger-ui/ "SwaggerUI site") |
| 84 | + |
| 85 | + |
| 86 | + |
| 87 | +### Postman |
| 88 | + |
| 89 | +This is how the swagger file would be rendered in [Postman](https://www.getpostman.com/ "Postman site") |
| 90 | + |
| 91 | + |
| 92 | + |
| 93 | +For a more detailed example of a protofile that has Go templates enabled, [click here](https://github.com/grpc-ecosystem/grpc-gateway/blob/master/examples/proto/examplepb/use_go_template.proto "Example protofile with Go template"). |
0 commit comments