Description
OpenAPI 2.0 recommends an operation summary shorter than 120 characters for readability in documentation tools. A long summary can reduce readability, but its length alone is neither an API security vulnerability nor a reason the specification is invalid.
Potential impact
- Readers may struggle to identify an operation’s purpose quickly in a list.
- A summary may be truncated or occupy too much space in generated documentation.
Remediation
Summarize the operation’s main purpose briefly and move detailed conditions or usage instructions to description. Preserve the meaning and check readability in the generated documentation.
Examples
The first example has a long summary containing unnecessary repeated characters.
Before
json
{
"swagger": "2.0",
"info": {
"title": "Simple API Overview",
"version": "1.0.0"
},
"paths": {
"/": {
"get": {
"operationId": "listVersionsv2",
"summary": "List API versionssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssss",
"responses": {
"200": {
"description": "200 response"
}
}
}
}
}
}
After
json
{
"swagger": "2.0",
"info": {
"title": "Simple API Overview",
"version": "1.0.0"
},
"paths": {
"/": {
"get": {
"operationId": "listVersionsv2",
"summary": "List API versions",
"produces": [
"application/json"
],
"responses": {
"200": {
"description": "200 response"
}
}
}
}
}
}
The second example expresses the operation’s purpose in a short sentence. Use description for necessary detail instead of removing it just to shorten the summary.