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