설명
OpenAPI 3.0과 2.0의 각 작업에는 비어 있지 않은 responses가 필요합니다. 적어도 하나의 응답 정의가 있어야 호출 결과를 설명할 수 있습니다. 사용하지 않는 재사용 응답 저장소인 components.responses나 OpenAPI 2.0의 최상위 responses가 비어 있는 것과는 다릅니다.
잠재적 영향
응답 계약이 없으면 API 소비자가 상태 코드와 데이터 형식을 알기 어렵고, SDK 생성이나 문서 기반 검증이 불완전해질 수 있습니다.
해결 방법
각 작업의 responses에 실제로 반환하는 응답을 하나 이상 정의하세요. 정상 응답과 알려진 오류를 설명하고, 적절한 경우 default를 사용하세요. 문서를 채우기 위해 서버가 반환하지 않는 200 응답을 만들지 마세요.
예시
OpenAPI 3.0 작업 응답의 발췌이며 info는 생략했습니다. 변경 전의 작업별 responses: {}에는 필요한 응답 정의가 없습니다.
변경 전
json
{
"openapi": "3.0.0",
"paths": {
"/": {
"get": {
"responses": {}
}
}
}
}
변경 후
json
{
"openapi": "3.0.0",
"paths": {
"/": {
"get": {
"responses": {
"200": {
"description": "OK"
}
}
}
}
}
}
변경 후에는 200 응답을 정의합니다. 이 상태가 실제 정상 응답인 경우의 예시이며, 반환하는 본문과 오류 응답도 실제 계약에 맞게 추가하세요.