OpenAPI 2.0 객체의 필수 속성 누락

설명

OpenAPI 2.0 객체에 필수 속성이 없으면 명세를 검증하거나 문서와 클라이언트를 생성하는 데 문제가 생길 수 있습니다. 필요한 속성은 객체 종류와 설정에 따라 다릅니다.

예를 들어 info에는 title과 version이 필요합니다. 본문 매개변수에는 schema가 필요하고, 본문 이외의 매개변수에는 type이 필요합니다. 보안 정의의 필수 속성도 인증 방식에 따라 달라집니다.

잠재적 영향

명세 검증이나 코드 생성이 실패할 수 있습니다.
입력과 응답의 의미가 불완전해 API 사용자와 구현자가 서로 다르게 해석할 수 있습니다.

해결 방법

OpenAPI 2.0에서 각 객체에 요구하는 속성과 조건을 확인하고 실제 API에 맞는 값을 추가하세요. 임의의 값을 채우기보다 문서와 구현을 일치시키고, 수정 후 명세를 검증하세요.

예시

첫 문서는 info.version과 query 매개변수의 type이 빠져 있습니다.

변경 전

json

{
  "swagger": "2.0",
  "info": {
    "title": "Simple API Overview"
  },
  "paths": {
    "/": {
      "get": {
        "operationId": "listVersionsv2",
        "summary": "List API versions",
        "responses": {
          "200": {
            "description": "200 response"
          }
        }
      }
    }
  },
  "parameters": {
    "limitParam": {
      "name": "limit",
      "in": "query",
      "description": "max records to return",
      "required": true
    }
  }
}

변경 후