설명
responses의 default는 개별적으로 정의하지 않은 상태 코드의 응답을 설명합니다. 선택 사항이며 오류 전용도 아니지만, 문서에 없는 응답들이 공통 형식을 사용한다면 이를 설명하는 데 유용합니다.
잠재적 영향
실제로 반환하는 오류 응답의 형식이 문서에 없으면 클라이언트나 생성된 SDK가 이를 제대로 처리하지 못할 수 있습니다.
해결 방법
알려진 성공 및 오류 응답을 문서화하고, 나머지 응답에 공통 계약이 필요한 경우 default를 추가하세요. 해당 응답의 의미와 실제로 반환하는 본문 형식을 설명하세요.
예시
다음 OpenAPI 3.0 발췌 예시는 본문 없는 204 성공 응답 외에, 개별적으로 정의하지 않은 오류 응답의 설명을 default로 추가합니다.
변경 전
json
{
"openapi": "3.0.0",
"paths": {
"/item": {
"patch": {
"operationId": "updateItem",
"responses": {
"204": {
"description": "Item updated successfully"
}
}
}
}
}
}
변경 후
json
{
"openapi": "3.0.0",
"paths": {
"/item": {
"patch": {
"operationId": "updateItem",
"responses": {
"204": {
"description": "Item updated successfully"
},
"default": {
"description": "Error"
}
}
}
}
}
}