Skip to content

Commit 03164ec

Browse files
yuguiyugui
committed
Merge pull request #156 from t-yuki/swagger_descriptions
Generate Swagger description for service methods using proto comments.
2 parents 03f88dc + 32d2d86 commit 03164ec

File tree

10 files changed

+397
-63
lines changed

10 files changed

+397
-63
lines changed

‎examples/examplepb/echo_service.pb.go‎

Lines changed: 17 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎examples/examplepb/echo_service.proto‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,32 @@
11
syntax = "proto3";
22
option go_package = "examplepb";
3+
4+
// Echo Service
5+
//
6+
// Echo Service API consists of a single service which returns
7+
// a message.
38
package gengo.grpc.gateway.examples.examplepb;
49

510
import "google/api/annotations.proto";
611

12+
// SimpleMessage represents a simple message sent to the Echo service.
713
message SimpleMessage {
14+
// Id represents the message identifier.
815
string id = 1;
916
}
1017

18+
// Echo service responds to incoming echo requests.
1119
service EchoService {
20+
// Echo method receives a simple message and returns it.
21+
//
22+
// The message posted as the id parameter will also be
23+
// returned.
1224
rpc Echo(SimpleMessage) returns (SimpleMessage) {
1325
option (google.api.http) = {
1426
post: "/v1/example/echo/{id}"
1527
};
1628
}
29+
// EchoBody method receives a simple message and returns it.
1730
rpc EchoBody(SimpleMessage) returns (SimpleMessage) {
1831
option (google.api.http) = {
1932
post: "/v1/example/echo_body"

‎examples/examplepb/echo_service.swagger.json‎

Lines changed: 12 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,9 @@
11
{
22
"swagger": "2.0",
33
"info": {
4-
"version": "",
5-
"title": ""
4+
"title": "Echo Service",
5+
"description": "Echo Service API consists of a single service which returns\na message.",
6+
"version": "version not set"
67
},
78
"schemes": [
89
"http",
@@ -17,10 +18,11 @@
1718
"paths": {
1819
"/v1/example/echo/{id}": {
1920
"post": {
20-
"summary": "EchoService.Echo",
21+
"summary": "Echo method receives a simple message and returns it.",
22+
"description": "The message posted as the id parameter will also be\nreturned.",
2123
"operationId": "Echo",
2224
"responses": {
23-
"default": {
25+
"200": {
2426
"description": "Description",
2527
"schema": {
2628
"$ref": "#/definitions/examplepbSimpleMessage"
@@ -43,10 +45,10 @@
4345
},
4446
"/v1/example/echo_body": {
4547
"post": {
46-
"summary": "EchoService.EchoBody",
48+
"summary": "EchoBody method receives a simple message and returns it.",
4749
"operationId": "EchoBody",
4850
"responses": {
49-
"default": {
51+
"200": {
5052
"description": "Description",
5153
"schema": {
5254
"$ref": "#/definitions/examplepbSimpleMessage"
@@ -75,9 +77,11 @@
7577
"properties": {
7678
"id": {
7779
"type": "string",
78-
"format": "string"
80+
"format": "string",
81+
"description": "Id represents the message identifier."
7982
}
80-
}
83+
},
84+
"description": "SimpleMessage represents a simple message sent to the Echo service."
8185
}
8286
}
8387
}

‎examples/examplepb/streamless_everything.proto‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,11 +8,16 @@ import "examples/sub/message.proto";
88
// Intentionaly complicated message type to cover much features of Protobuf.
99
// NEXT ID: 27
1010
message ABitOfEverything {
11+
// Nested is nested type.
1112
message Nested {
13+
// name is nested field.
1214
string name = 1;
1315
uint32 amount = 2;
16+
// DeepEnum is one or zero.
1417
enum DeepEnum {
18+
// FALSE is false.
1519
FALSE = 0;
20+
// TRUE is true.
1621
TRUE = 1;
1722
}
1823
DeepEnum ok = 3;
@@ -54,11 +59,15 @@ message EmptyMessage {
5459
}
5560

5661
message IdMessage {
62+
// uuid is UUID value
5763
string uuid = 1;
5864
}
5965

66+
// NumericEnum is one or zero.
6067
enum NumericEnum {
68+
// ZERO means 0
6169
ZERO = 0;
70+
// ONE means 1
6271
ONE = 1;
6372
}
6473

‎examples/examplepb/streamless_everything.swagger.json‎

Lines changed: 26 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
{
22
"swagger": "2.0",
33
"info": {
4-
"version": "",
5-
"title": ""
4+
"title": "examples/examplepb/streamless_everything.proto",
5+
"version": "version not set"
66
},
77
"schemes": [
88
"http",
@@ -17,10 +17,9 @@
1717
"paths": {
1818
"/v1/example/a_bit_of_everything": {
1919
"get": {
20-
"summary": "ABitOfEverythingService.List",
2120
"operationId": "List",
2221
"responses": {
23-
"default": {
22+
"200": {
2423
"description": "Description",
2524
"schema": {
2625
"$ref": "#/definitions/examplepbABitOfEverything"
@@ -32,10 +31,9 @@
3231
]
3332
},
3433
"post": {
35-
"summary": "ABitOfEverythingService.CreateBody",
3634
"operationId": "CreateBody",
3735
"responses": {
38-
"default": {
36+
"200": {
3937
"description": "Description",
4038
"schema": {
4139
"$ref": "#/definitions/examplepbABitOfEverything"
@@ -59,10 +57,9 @@
5957
},
6058
"/v1/example/a_bit_of_everything/bulk": {
6159
"post": {
62-
"summary": "ABitOfEverythingService.BulkCreate",
6360
"operationId": "BulkCreate",
6461
"responses": {
65-
"default": {
62+
"200": {
6663
"description": "Description",
6764
"schema": {
6865
"$ref": "#/definitions/examplepbEmptyMessage"
@@ -86,10 +83,9 @@
8683
},
8784
"/v1/example/a_bit_of_everything/echo": {
8885
"post": {
89-
"summary": "ABitOfEverythingService.BulkEcho",
9086
"operationId": "BulkEcho",
9187
"responses": {
92-
"default": {
88+
"200": {
9389
"description": "Description",
9490
"schema": {
9591
"$ref": "#/definitions/subStringMessage"
@@ -113,10 +109,9 @@
113109
},
114110
"/v1/example/a_bit_of_everything/echo/{value}": {
115111
"get": {
116-
"summary": "ABitOfEverythingService.Echo",
117112
"operationId": "Echo",
118113
"responses": {
119-
"default": {
114+
"200": {
120115
"description": "Description",
121116
"schema": {
122117
"$ref": "#/definitions/subStringMessage"
@@ -139,10 +134,9 @@
139134
},
140135
"/v1/example/a_bit_of_everything/{float_value}/{double_value}/{int64_value}/separator/{uint64_value}/{int32_value}/{fixed64_value}/{fixed32_value}/{bool_value}/{string_value}/{uint32_value}/{sfixed32_value}/{sfixed64_value}/{sint32_value}/{sint64_value}/{nonConventionalNameValue}": {
141136
"post": {
142-
"summary": "ABitOfEverythingService.Create",
143137
"operationId": "Create",
144138
"responses": {
145-
"default": {
139+
"200": {
146140
"description": "Description",
147141
"schema": {
148142
"$ref": "#/definitions/examplepbABitOfEverything"
@@ -263,10 +257,9 @@
263257
},
264258
"/v1/example/a_bit_of_everything/{single_nested.name}": {
265259
"post": {
266-
"summary": "ABitOfEverythingService.DeepPathEcho",
267260
"operationId": "DeepPathEcho",
268261
"responses": {
269-
"default": {
262+
"200": {
270263
"description": "Description",
271264
"schema": {
272265
"$ref": "#/definitions/examplepbABitOfEverything"
@@ -297,10 +290,9 @@
297290
},
298291
"/v1/example/a_bit_of_everything/{uuid}": {
299292
"get": {
300-
"summary": "ABitOfEverythingService.Lookup",
301293
"operationId": "Lookup",
302294
"responses": {
303-
"default": {
295+
"200": {
304296
"description": "Description",
305297
"schema": {
306298
"$ref": "#/definitions/examplepbABitOfEverything"
@@ -321,10 +313,9 @@
321313
]
322314
},
323315
"delete": {
324-
"summary": "ABitOfEverythingService.Delete",
325316
"operationId": "Delete",
326317
"responses": {
327-
"default": {
318+
"200": {
328319
"description": "Description",
329320
"schema": {
330321
"$ref": "#/definitions/examplepbEmptyMessage"
@@ -345,10 +336,9 @@
345336
]
346337
},
347338
"put": {
348-
"summary": "ABitOfEverythingService.Update",
349339
"operationId": "Update",
350340
"responses": {
351-
"default": {
341+
"200": {
352342
"description": "Description",
353343
"schema": {
354344
"$ref": "#/definitions/examplepbEmptyMessage"
@@ -388,20 +378,23 @@
388378
},
389379
"name": {
390380
"type": "string",
391-
"format": "string"
381+
"format": "string",
382+
"description": "name is nested field."
392383
},
393384
"ok": {
394385
"$ref": "#/definitions/NestedDeepEnum"
395386
}
396-
}
387+
},
388+
"description": "Nested is nested type."
397389
},
398390
"NestedDeepEnum": {
399391
"type": "string",
400392
"enum": [
401393
"FALSE",
402394
"TRUE"
403395
],
404-
"default": "FALSE"
396+
"default": "FALSE",
397+
"description": "DeepEnum is one or zero.\n\n - FALSE: FALSE is false.\n - TRUE: TRUE is true."
405398
},
406399
"examplepbABitOfEverything": {
407400
"type": "object",
@@ -505,7 +498,8 @@
505498
},
506499
"uint32_value": {
507500
"type": "integer",
508-
"format": "int64"
501+
"format": "int64",
502+
"title": "TODO(yugui) add bytes_value"
509503
},
510504
"uint64_value": {
511505
"type": "integer",
@@ -515,7 +509,8 @@
515509
"type": "string",
516510
"format": "string"
517511
}
518-
}
512+
},
513+
"title": "Intentionaly complicated message type to cover much features of Protobuf.\nNEXT ID: 27"
519514
},
520515
"examplepbEmptyMessage": {
521516
"type": "object"
@@ -525,7 +520,8 @@
525520
"properties": {
526521
"uuid": {
527522
"type": "string",
528-
"format": "string"
523+
"format": "string",
524+
"title": "uuid is UUID value"
529525
}
530526
}
531527
},
@@ -535,7 +531,8 @@
535531
"ZERO",
536532
"ONE"
537533
],
538-
"default": "ZERO"
534+
"default": "ZERO",
535+
"description": "NumericEnum is one or zero.\n\n - ZERO: ZERO means 0\n - ONE: ONE means 1"
539536
},
540537
"subStringMessage": {
541538
"type": "object",

‎protoc-gen-grpc-gateway/descriptor/registry.go‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -99,11 +99,12 @@ func (r *Registry) loadFile(file *descriptor.FileDescriptorProto) {
9999
}
100100

101101
func (r *Registry) registerMsg(file *File, outerPath []string, msgs []*descriptor.DescriptorProto) {
102-
for _, md := range msgs {
102+
for i, md := range msgs {
103103
m := &Message{
104104
File: file,
105105
Outers: outerPath,
106106
DescriptorProto: md,
107+
Index: i,
107108
}
108109
for _, fd := range md.GetField() {
109110
m.Fields = append(m.Fields, &Field{
@@ -124,11 +125,12 @@ func (r *Registry) registerMsg(file *File, outerPath []string, msgs []*descripto
124125
}
125126

126127
func (r *Registry) registerEnum(file *File, outerPath []string, enums []*descriptor.EnumDescriptorProto) {
127-
for _, ed := range enums {
128+
for i, ed := range enums {
128129
e := &Enum{
129130
File: file,
130131
Outers: outerPath,
131132
EnumDescriptorProto: ed,
133+
Index: i,
132134
}
133135
file.Enums = append(file.Enums, e)
134136
r.enums[e.FQEN()] = e

0 commit comments

Comments
 (0)