설명
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을 활용하세요.