설명
OpenAPI 문서는 작업이 실제로 반환하는 성공 응답과 알려진 오류 응답을 설명해야 합니다. 모든 작업에 같은 상태 코드 목록이 필수인 것은 아니며, 실제 API 계약에 맞춰 정의해야 합니다.
잠재적 영향
클라이언트와 테스트가 오류를 잘못 처리하거나 실제 서버와 다른 응답을 예상할 수 있습니다.
해결 방법
작업별로 발생 가능한 응답의 상태 코드와 의미, 헤더, 필요한 본문 스키마를 정의하세요. 인증 실패, 접근 거부, 요청 제한 같은 상황도 실제 지원하는 동작에 맞게 설명하세요.
예시
다음 OpenAPI 3.0 발췌 예시는 PUT의 일부 오류 응답과 OPTIONS의 응답을 명시합니다. 보편적으로 필요한 코드 목록은 아니며, PUT의 성공 응답 등은 이 예시에서 생략했습니다.
변경 전
json
{
"openapi": "3.0.0",
"paths": {
"/item": {
"put": {
"responses": {
"default": {
"description": "Error"
}
}
},
"options": {
"responses": {
"default": {
"description": "Error"
}
}
}
}
}
}
변경 후
json
{
"openapi": "3.0.0",
"paths": {
"/item": {
"put": {
"responses": {
"400": { "description": "400 response" },
"404": { "description": "404 response" },
"415": { "description": "415 response" },
"429": { "description": "429 response" },
"500": { "description": "500 response" }
}
},
"options": {
"responses": {
"200": { "description": "200 response" },
"400": { "description": "400 response" },
"429": { "description": "429 response" },
"500": { "description": "500 response" }
}
}
}
}
}