설명
PUT은 대상 리소스를 생성하거나 교체하는 데 사용됩니다. 성공 응답을 문서화하지 않으면 호출자가 생성과 기존 리소스 갱신의 결과를 구분하기 어렵습니다.
잠재적 영향
클라이언트와 테스트가 서버의 생성 또는 갱신 결과를 잘못 해석할 수 있습니다.
해결 방법
새 리소스 생성은 201, 기존 리소스 갱신 후 본문이 없으면 204, 본문이 있으면 200 등 실제 동작에 맞는 응답을 정의하세요. 본문을 반환하는 경우에만 해당 스키마를 추가하세요.
예시
다음 OpenAPI 3.0 발췌 예시는 새 항목 생성의 201과 본문 없는 기존 항목 갱신의 204를 구분합니다.
변경 전
json
{
"openapi": "3.0.0",
"paths": {
"/item": {
"put": {
"operationId": "updateItem",
"summary": "Update item",
"responses": {
"default": {
"description": "Error"
}
}
}
}
}
}
변경 후
json
{
"openapi": "3.0.0",
"paths": {
"/item": {
"put": {
"operationId": "updateItem",
"summary": "Update item",
"responses": {
"201": {
"description": "Item created successfully"
},
"204": {
"description": "Item updated successfully"
},
"default": {
"description": "Error"
}
}
}
}
}
}