protoc-gen-swagger emits method summary and descriptions

* Fix protoc-gen-swagger to output gRPC method summary and descriptions as Swagger expects. * Add a gRPC method comment to examples proto and regenerate examples
grpc-ecosystem · Jun 22, 2018 · 11bef10 · 11bef10
1 parent ffaaaf2
commit 11bef10
Show file tree

Hide file tree

Showing 6 changed files with 51 additions and 26 deletions.
diff --git a/examples/clients/abe/a_bit_of_everything_service_api.go b/examples/clients/abe/a_bit_of_everything_service_api.go
@@ -39,7 +39,8 @@ func NewABitOfEverythingServiceApiWithBasePath(basePath string) *ABitOfEverythin
 }
 
 /**
- * 
+ * Create a new ABitOfEverything
+ * This API creates a new ABitOfEverything
  *
  * @param floatValue 
  * @param doubleValue 

diff --git a/examples/clients/abe/camel_case_service_name_api.go b/examples/clients/abe/camel_case_service_name_api.go
@@ -37,7 +37,8 @@ func NewCamelCaseServiceNameApiWithBasePath(basePath string) *CamelCaseServiceNa
 }
 
 /**
- * 
+ * Create a new ABitOfEverything
+ * This API creates a new ABitOfEverything
  *
  * @return *ProtobufEmpty
  */

diff --git a/examples/proto/examplepb/a_bit_of_everything.pb.go b/examples/proto/examplepb/a_bit_of_everything.pb.go
diff --git a/examples/proto/examplepb/a_bit_of_everything.proto b/examples/proto/examplepb/a_bit_of_everything.proto
@@ -221,6 +221,9 @@ service ABitOfEverythingService {
 		}
 	};
 
+	// Create a new ABitOfEverything
+	//
+	// This API creates a new ABitOfEverything
 	rpc Create(ABitOfEverything) returns (ABitOfEverything) {
 		// TODO add enum_value
 		option (google.api.http) = {

diff --git a/examples/proto/examplepb/a_bit_of_everything.swagger.json b/examples/proto/examplepb/a_bit_of_everything.swagger.json
@@ -348,6 +348,8 @@
     },
     "/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}": {
       "post": {
+        "summary": "Create a new ABitOfEverything",
+        "description": "This API creates a new ABitOfEverything",
         "operationId": "Create",
         "responses": {
           "200": {
@@ -770,6 +772,8 @@
     },
     "/v2/example/empty": {
       "get": {
+        "summary": "Create a new ABitOfEverything",
+        "description": "This API creates a new ABitOfEverything",
         "operationId": "Empty",
         "responses": {
           "200": {

diff --git a/protoc-gen-swagger/genswagger/template.go b/protoc-gen-swagger/genswagger/template.go
@@ -627,7 +627,7 @@ func renderServices(services []*descriptor.Service, paths swaggerPathsObject, re
 					}
 				}
 
-				methComments := protoComments(reg, svc.File, nil, "Service", int32(svcIdx), methProtoPath, int32(methIdx))
+				methComments := protoComments(reg, svc.File, nil, "Method", int32(svcIdx), methProtoPath, int32(methIdx))
 				if err := updateSwaggerDataFromComments(operationObject, methComments); err != nil {
 					panic(err)
 				}
@@ -1069,6 +1069,8 @@ func protoComments(reg *descriptor.Registry, file *descriptor.File, outers []str
 var messageProtoPath = protoPathIndex(reflect.TypeOf((*pbdescriptor.FileDescriptorProto)(nil)), "MessageType")
 var nestedProtoPath = protoPathIndex(reflect.TypeOf((*pbdescriptor.DescriptorProto)(nil)), "NestedType")
 var packageProtoPath = protoPathIndex(reflect.TypeOf((*pbdescriptor.FileDescriptorProto)(nil)), "Package")
+var serviceProtoPath = protoPathIndex(reflect.TypeOf((*pbdescriptor.FileDescriptorProto)(nil)), "Service")
+var methodProtoPath = protoPathIndex(reflect.TypeOf((*pbdescriptor.ServiceDescriptorProto)(nil)), "Method")
 
 func isProtoPathMatches(paths []int32, outerPaths []int32, typeName string, typeIndex int32, fieldPaths []int32) bool {
 	if typeName == "Package" && typeIndex == packageProtoPath {
@@ -1084,31 +1086,39 @@ func isProtoPathMatches(paths []int32, outerPaths []int32, typeName string, type
 		return false
 	}
 
-	typeNameDescriptor := reflect.TypeOf((*pbdescriptor.FileDescriptorProto)(nil))
-	if len(outerPaths) > 0 {
-		if paths[0] != messageProtoPath || paths[1] != outerPaths[0] {
+	if typeName == "Method" {
+		if paths[0] != serviceProtoPath || paths[2] != methodProtoPath {
 			return false
 		}
 		paths = paths[2:]
-		outerPaths = outerPaths[1:]
+	} else {
+		typeNameDescriptor := reflect.TypeOf((*pbdescriptor.FileDescriptorProto)(nil))
 
-		for i, v := range outerPaths {
-			if paths[i*2] != nestedProtoPath || paths[i*2+1] != v {
+		if len(outerPaths) > 0 {
+			if paths[0] != messageProtoPath || paths[1] != outerPaths[0] {
 				return false
 			}
-		}
-		paths = paths[len(outerPaths)*2:]
+			paths = paths[2:]
+			outerPaths = outerPaths[1:]
+
+			for i, v := range outerPaths {
+				if paths[i*2] != nestedProtoPath || paths[i*2+1] != v {
+					return false
+				}
+			}
+			paths = paths[len(outerPaths)*2:]
 
-		if typeName == "MessageType" {
-			typeName = "NestedType"
+			if typeName == "MessageType" {
+				typeName = "NestedType"
+			}
+			typeNameDescriptor = reflect.TypeOf((*pbdescriptor.DescriptorProto)(nil))
 		}
-		typeNameDescriptor = reflect.TypeOf((*pbdescriptor.DescriptorProto)(nil))
-	}
 
-	if paths[0] != protoPathIndex(typeNameDescriptor, typeName) || paths[1] != typeIndex {
-		return false
+		if paths[0] != protoPathIndex(typeNameDescriptor, typeName) || paths[1] != typeIndex {
+			return false
+		}
+		paths = paths[2:]
 	}
-	paths = paths[2:]
 
 	for i, v := range fieldPaths {
 		if paths[i] != v {