Populate swagger method parameter description from message comments

grpc-ecosystem · Jul 3, 2018 · 14eab3f · 14eab3f
1 parent 39a18c6
commit 14eab3f
Show file tree

Hide file tree

Showing 7 changed files with 31 additions and 13 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
@@ -219,7 +219,7 @@ func (a ABitOfEverythingServiceApi) CreateBody(body ExamplepbABitOfEverything) (
 /**
  * 
  *
- * @param singleNestedName 
+ * @param singleNestedName name is nested field.
  * @param body 
  * @return *ExamplepbABitOfEverything
  */

diff --git a/examples/clients/echo/echo_service_api.go b/examples/clients/echo/echo_service_api.go
@@ -41,7 +41,7 @@ func NewEchoServiceApiWithBasePath(basePath string) *EchoServiceApi {
  * Echo method receives a simple message and returns it.
  * The message posted as the id parameter will also be returned.
  *
- * @param id 
+ * @param id Id represents the message identifier.
  * @return *ExamplepbSimpleMessage
  */
 func (a EchoServiceApi) Echo(id string) (*ExamplepbSimpleMessage, *APIResponse, error) {
@@ -102,7 +102,7 @@ func (a EchoServiceApi) Echo(id string) (*ExamplepbSimpleMessage, *APIResponse,
  * Echo method receives a simple message and returns it.
  * The message posted as the id parameter will also be returned.
  *
- * @param id 
+ * @param id Id represents the message identifier.
  * @param num 
  * @param lineNum 
  * @param lang 
@@ -179,7 +179,7 @@ func (a EchoServiceApi) Echo2(id string, num string, lineNum string, lang string
  * Echo method receives a simple message and returns it.
  * The message posted as the id parameter will also be returned.
  *
- * @param id 
+ * @param id Id represents the message identifier.
  * @param num 
  * @param lang 
  * @param lineNum 
@@ -256,7 +256,7 @@ func (a EchoServiceApi) Echo3(id string, num string, lang string, lineNum string
  * Echo method receives a simple message and returns it.
  * The message posted as the id parameter will also be returned.
  *
- * @param id 
+ * @param id Id represents the message identifier.
  * @param lineNum 
  * @param statusNote 
  * @param num 

diff --git a/examples/clients/unannotatedecho/unannotated_echo_service_api.go b/examples/clients/unannotatedecho/unannotated_echo_service_api.go
@@ -41,7 +41,7 @@ func NewUnannotatedEchoServiceApiWithBasePath(basePath string) *UnannotatedEchoS
  * Echo method receives a simple message and returns it.
  * The message posted as the id parameter will also be returned.
  *
- * @param id 
+ * @param id Id represents the message identifier.
  * @return *ExamplepbUnannotatedSimpleMessage
  */
 func (a UnannotatedEchoServiceApi) Echo(id string) (*ExamplepbUnannotatedSimpleMessage, *APIResponse, error) {
@@ -102,7 +102,7 @@ func (a UnannotatedEchoServiceApi) Echo(id string) (*ExamplepbUnannotatedSimpleM
  * Echo method receives a simple message and returns it.
  * The message posted as the id parameter will also be returned.
  *
- * @param id 
+ * @param id Id represents the message identifier.
  * @param num 
  * @param duration 
  * @return *ExamplepbUnannotatedSimpleMessage

diff --git a/examples/proto/examplepb/a_bit_of_everything.swagger.json b/examples/proto/examplepb/a_bit_of_everything.swagger.json
@@ -516,6 +516,7 @@
         "parameters": [
           {
             "name": "single_nested.name",
+            "description": "name is nested field.",
             "in": "path",
             "required": true,
             "type": "string"

diff --git a/examples/proto/examplepb/echo_service.swagger.json b/examples/proto/examplepb/echo_service.swagger.json
@@ -32,6 +32,7 @@
         "parameters": [
           {
             "name": "id",
+            "description": "Id represents the message identifier.",
             "in": "path",
             "required": true,
             "type": "string"
@@ -58,6 +59,7 @@
         "parameters": [
           {
             "name": "id",
+            "description": "Id represents the message identifier.",
             "in": "path",
             "required": true,
             "type": "string"
@@ -137,6 +139,7 @@
         "parameters": [
           {
             "name": "id",
+            "description": "Id represents the message identifier.",
             "in": "path",
             "required": true,
             "type": "string"
@@ -216,6 +219,7 @@
         "parameters": [
           {
             "name": "id",
+            "description": "Id represents the message identifier.",
             "in": "path",
             "required": true,
             "type": "string"

diff --git a/examples/proto/examplepb/unannotated_echo_service.swagger.json b/examples/proto/examplepb/unannotated_echo_service.swagger.json
@@ -32,6 +32,7 @@
         "parameters": [
           {
             "name": "id",
+            "description": "Id represents the message identifier.",
             "in": "path",
             "required": true,
             "type": "string"
@@ -58,6 +59,7 @@
         "parameters": [
           {
             "name": "id",
+            "description": "Id represents the message identifier.",
             "in": "path",
             "required": true,
             "type": "string"

diff --git a/protoc-gen-swagger/genswagger/template.go b/protoc-gen-swagger/genswagger/template.go
@@ -524,13 +524,14 @@ func renderServices(services []*descriptor.Service, paths swaggerPathsObject, re
 				parameters := swaggerParametersObject{}
 				for _, parameter := range b.PathParams {
 
-					var paramType, paramFormat string
+					var paramType, paramFormat, desc string
 					switch pt := parameter.Target.GetType(); pt {
 					case pbdescriptor.FieldDescriptorProto_TYPE_GROUP, pbdescriptor.FieldDescriptorProto_TYPE_MESSAGE:
 						if descriptor.IsWellKnownType(parameter.Target.GetTypeName()) {
 							schema := schemaOfField(parameter.Target, reg, customRefs)
 							paramType = schema.Type
 							paramFormat = schema.Format
+							desc = schema.Description
 						} else {
 							return fmt.Errorf("only primitive and well-known types are allowed in path parameters")
 						}
@@ -545,10 +546,15 @@ func renderServices(services []*descriptor.Service, paths swaggerPathsObject, re
 						}
 					}
 
+					if desc == "" {
+						desc = fieldProtoComments(reg, parameter.Target.Message, parameter.Target)
+					}
+
 					parameters = append(parameters, swaggerParameterObject{
-						Name:     parameter.String(),
-						In:       "path",
-						Required: true,
+						Name:        parameter.String(),
+						Description: desc,
+						In:          "path",
+						Required:    true,
 						// Parameters in gRPC-Gateway can only be strings?
 						Type:   paramType,
 						Format: paramFormat,
@@ -557,6 +563,7 @@ func renderServices(services []*descriptor.Service, paths swaggerPathsObject, re
 				// Now check if there is a body parameter
 				if b.Body != nil {
 					var schema swaggerSchemaObject
+					desc := ""
 
 					if len(b.Body.FieldPath) == 0 {
 						schema = swaggerSchemaObject{
@@ -567,11 +574,15 @@ func renderServices(services []*descriptor.Service, paths swaggerPathsObject, re
 					} else {
 						lastField := b.Body.FieldPath[len(b.Body.FieldPath)-1]
 						schema = schemaOfField(lastField.Target, reg, customRefs)
+						if schema.Description != "" {
+							desc = schema.Description
+						} else {
+							desc = fieldProtoComments(reg, lastField.Target.Message, lastField.Target)
+						}
 					}
 
-					desc := ""
 					if meth.GetClientStreaming() {
-						desc = "(streaming inputs)"
+						desc = desc + "(streaming inputs)"
 					}
 					parameters = append(parameters, swaggerParameterObject{
 						Name:        "body",