diff --git a/examples/clients/abe/a_bit_of_everything_service_api.go b/examples/clients/abe/a_bit_of_everything_service_api.go index 4cc9d609e59..f07085ef4a0 100644 --- 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 index 775d0b3a7e6..6ae7cf85a32 100644 --- 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 index 99f02f08d03..cb3efdde4d4 100644 --- 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 index 4b82a011b2d..babfb987a8e 100644 --- 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 index c14354ffbce..ddcf349261d 100644 --- 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 index 9bfa9f28ba6..fcbf16573ee 100644 --- 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 index 0ffe369cc9f..f12ea38f724 100644 --- 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 += " (streaming inputs)" } parameters = append(parameters, swaggerParameterObject{ Name: "body",