설명
GET 작업의 성공 상태 코드와 결과를 명시하지 않으면 호출자가 정상 조회 결과를 추측해야 합니다. default는 오류뿐 아니라 개별 정의가 없는 다른 응답도 포함할 수 있어, 성공 결과를 명확히 설명하지 못할 수 있습니다.
잠재적 영향
클라이언트와 테스트가 정상 응답의 상태 코드나 데이터 형식을 다르게 예상할 수 있습니다.
해결 방법
일반적인 조회 결과의 200처럼 실제로 반환하는 성공 코드를 정의하세요. 부분 콘텐츠의 206 등 다른 성공 코드를 사용한다면 그 의미와 응답 형식도 문서화하세요.
예시
다음 OpenAPI 2.0 발췌 예시는 조회 성공을 나타내는 200을 추가합니다. 응답 본문 스키마는 이 예시에서 생략했습니다.
변경 전
json
{
"swagger": "2.0",
"paths": {
"/item": {
"get": {
"operationId": "getItem",
"summary": "Get item",
"responses": {
"default": {
"description": "Error"
}
}
}
}
}
}
변경 후
json
{
"swagger": "2.0",
"paths": {
"/item": {
"get": {
"operationId": "getItem",
"summary": "Get item",
"responses": {
"200": {
"description": "Success"
},
"default": {
"description": "Error"
}
}
}
}
}
}