Comments on a property of a message that are other proto messages become title breaking Swagger generation #3381
Description
🐛 Bug Report
This is similar in nature to #2670 but is related to message properties that refer to another proto message (or repeated messages)
When you have a message and that field has a comment on it that doesn't contain a blank line, the comment becomes the "title" of the body parameter making it fail generation with the Swagger generator as it's much too long and contains extra lines. It really should become the "description" or "summary" but definitely not the "title". We should really always prevent the "title" from having any line breaks in it at all. Right now we only consider double line breaks.
To Reproduce
When you have the following:
message MyRequestMessage {
// a comment about my body parameter that is quite long
// and may have multiple lines
// that should become the description of the body parameter or potentially the "summary"
AnotherMessage my_body_parameter = 1;
string a_query_parameter = 2;
}
...
service MyService {
// Makes a request
rpc MakeMyRequest(MyRequestMessage) returns (google.type.Empty) {
option (google.api.http) = {
post: "/a/path
body: "my_body_parameter"
}
}
}
## Expected behavior
What it should produce:
```json
"/a/path": {
"post": {
"summary": "Makes a request",
"operationId": "MyService_MakeMyRequest",
"responses": {
"200": {
"description": "A successful response.",
"schema": {
"$ref": "#/definitions/googletypeEmpty"
}
},
"default": {
"description": "An unexpected error response.",
"schema": {
"$ref": "#/definitions/googlerpcStatus"
}
}
},
"parameters": [
{
"name": "a_query_a_parameter",
"in": "query",
"required": false,
"type": "string"
},
{
"name": "my_body_parameter",
"summary": "a comment about my body parameter that is quite long\nand may have multiple lines\nthat should become the description of the body parameter or potentially the \"summary\"",
"in": "body",
"required": true,
"schema": {
...
}
}
]
}
}Actual Behavior
The generated OpenAPI specification is:
```json
"/a/path": {
"post": {
"summary": "Makes a request",
"operationId": "MyService_MakeMyRequest",
"responses": {
"200": {
"description": "A successful response.",
"schema": {
"$ref": "#/definitions/googletypeEmpty"
}
},
"default": {
"description": "An unexpected error response.",
"schema": {
"$ref": "#/definitions/googlerpcStatus"
}
}
},
"parameters": [
{
"name": "a_query_a_parameter",
"in": "query",
"required": false,
"type": "string"
},
{
"name": "my_body_parameter",
"title": "a comment about my body parameter that is quite long\nand may have multiple lines\nthat should become the description of the body parameter or potentially the \"summary\"",
"in": "body",
"required": true,
"schema": {
...
}
}
]
}
}
Cause
This is caused by the renderFieldAsDefinition method in template.go:
comments := fieldProtoComments(reg, f.Message, f)
if len(comments) > 0 {
// Use title and description from field instead of nested message if present.
paragraphs := strings.Split(comments, paragraphDeliminator)
schema.Title = strings.TrimSpace(paragraphs[0])
schema.Description = strings.TrimSpace(strings.Join(paragraphs[1:], paragraphDeliminator))
}This handling is inconsistent with the handling in renderMessageAsDefinition as processes through updateOpenAPIDataFromComments which would end up setting the "Summary" property from the message primary comments.