Skip to content

Commit

Permalink
Populate swagger method parameter description from message comments
Browse files Browse the repository at this point in the history
  • Loading branch information
co3k committed Jul 3, 2018
1 parent 39a18c6 commit 14eab3f
Show file tree
Hide file tree
Showing 7 changed files with 31 additions and 13 deletions.
2 changes: 1 addition & 1 deletion examples/clients/abe/a_bit_of_everything_service_api.go
Original file line number Diff line number Diff line change
Expand Up @@ -219,7 +219,7 @@ func (a ABitOfEverythingServiceApi) CreateBody(body ExamplepbABitOfEverything) (
/**
*
*
* @param singleNestedName
* @param singleNestedName name is nested field.
* @param body
* @return *ExamplepbABitOfEverything
*/
Expand Down
8 changes: 4 additions & 4 deletions examples/clients/echo/echo_service_api.go
Original file line number Diff line number Diff line change
Expand Up @@ -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) {
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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) {
Expand Down Expand Up @@ -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
Expand Down
1 change: 1 addition & 0 deletions examples/proto/examplepb/a_bit_of_everything.swagger.json
Original file line number Diff line number Diff line change
Expand Up @@ -516,6 +516,7 @@
"parameters": [
{
"name": "single_nested.name",
"description": "name is nested field.",
"in": "path",
"required": true,
"type": "string"
Expand Down
4 changes: 4 additions & 0 deletions examples/proto/examplepb/echo_service.swagger.json
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,7 @@
"parameters": [
{
"name": "id",
"description": "Id represents the message identifier.",
"in": "path",
"required": true,
"type": "string"
Expand All @@ -58,6 +59,7 @@
"parameters": [
{
"name": "id",
"description": "Id represents the message identifier.",
"in": "path",
"required": true,
"type": "string"
Expand Down Expand Up @@ -137,6 +139,7 @@
"parameters": [
{
"name": "id",
"description": "Id represents the message identifier.",
"in": "path",
"required": true,
"type": "string"
Expand Down Expand Up @@ -216,6 +219,7 @@
"parameters": [
{
"name": "id",
"description": "Id represents the message identifier.",
"in": "path",
"required": true,
"type": "string"
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,7 @@
"parameters": [
{
"name": "id",
"description": "Id represents the message identifier.",
"in": "path",
"required": true,
"type": "string"
Expand All @@ -58,6 +59,7 @@
"parameters": [
{
"name": "id",
"description": "Id represents the message identifier.",
"in": "path",
"required": true,
"type": "string"
Expand Down
23 changes: 17 additions & 6 deletions protoc-gen-swagger/genswagger/template.go
Original file line number Diff line number Diff line change
Expand Up @@ -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")
}
Expand All @@ -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,
Expand All @@ -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{
Expand All @@ -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",
Expand Down

0 comments on commit 14eab3f

Please sign in to comment.