설명
OpenAPI 작업의 responses는 실제 정상 처리 결과와 알려진 오류를 설명해야 합니다. 정상 결과가 누락되면 API 사용자가 기대할 응답을 이해하기 어렵습니다. 2xx가 없다는 사실만으로 문서가 잘못된 것은 아니며, 리디렉션 등 작업의 의도된 동작을 함께 확인해야 합니다.
잠재적 영향
클라이언트 구현이나 테스트가 실제 정상 응답을 오류로 처리하거나 필요한 응답 본문을 놓칠 수 있습니다.
해결 방법
실제 동작에 맞는 상태 코드와 설명, 필요한 헤더·본문을 정의하세요. 200, 201, 204 등을 관례만으로 추가하지 마세요. OpenAPI 3.0의 2XX 범위 응답과 default가 포괄하는 응답도 검토하고, 사용 중인 버전에서 허용하는 형식을 따르세요.
예시
작업의 응답 부분만 보여주는 OpenAPI 3.0 발췌이며 info는 생략했습니다. 300은 유효한 HTTP 상태 코드이므로 의도된 결과인지 확인해야 합니다.
변경 전
json
{
"openapi": "3.0.0",
"paths": {
"/": {
"get": {
"responses": {
"300": {
"description": "Redirect"
}
}
}
}
}
}
변경 후
json
{
"openapi": "3.0.0",
"paths": {
"/": {
"get": {
"responses": {
"200": {
"description": "OK"
}
}
}
}
}
}
변경 후는 실제 동작이 성공한 일반 응답을 반환한다는 가정으로 200을 정의합니다. 서버가 리디렉션을 반환하는데 문서만 200으로 바꾸면 계약이 잘못되므로 실제 응답에 맞추세요.