설명
OpenAPI 문서의 paths는 API 경로와 작업을 설명합니다. 빈 paths: {}에는 경로 정보가 없지만, OpenAPI 3.0과 2.0은 접근 제어에 따른 빈 객체를 허용합니다. 필수 paths 필드의 누락이나 null은 빈 객체와 다릅니다.
잠재적 영향
문서 대상 사용자에게 필요한 경로까지 빠지면 API를 탐색하거나 문서를 기반으로 연동·테스트하기 어렵습니다. 빈 문서가 실제 API의 비활성화나 접근 차단을 의미하지는 않습니다.
해결 방법
문서의 공개 대상과 범위를 확인하고 제공해야 할 실제 경로, 작업과 응답을 paths에 정의하세요. 접근 제어상 의도한 빈 객체는 유지할 수 있습니다. 서버의 인증과 권한 제어는 문서 공개 여부와 별도로 관리하세요.
예시
OpenAPI 3.0의 경로 공개 범위를 비교하는 발췌입니다. info는 생략했습니다. 변경 전의 빈 객체도 의도적인 문서 필터링에 사용할 수 있습니다.
변경 전
json
{
"openapi": "3.0.0",
"paths": {}
}
변경 후
json
{
"openapi": "3.0.0",
"paths": {
"/": {
"get": {
"responses": {
"200": {
"description": "OK"
}
}
}
}
}
}
변경 후에는 GET /와 응답을 공개합니다. 실제로 지원하고 이 문서의 대상에게 제공할 작업일 때 추가하세요.