説明
OpenAPI 2.0 は、文書ツールでの読みやすさのために操作の summary を 120 文字未満にすることを推奨しています。長い summary は読みにくくなりますが、長さだけで API のセキュリティ脆弱性になったり、仕様書が無効になったりするわけではありません。
想定される影響
- 一覧から操作の目的を素早く把握しにくくなります。
- 文書画面で要約が省略表示されたり、広い領域を占めたりする場合があります。
対処方法
summary には操作の主な目的を短く記載し、詳しい条件や使用方法は description に移してください。意味を保ちながら整理し、生成した文書で読みやすさを確認してください。
例
最初の例では、不要な文字の繰り返しによって summary が長くなっています。
変更前
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"
}
}
}
}
}
}
変更後
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"
}
}
}
}
}
}
変更後は操作の目的を短い文で表現しています。要約を短くするためだけに必要な説明を削除せず、description を使用してください。