OpenAPI 속성 이름과 위치 점검

설명

OpenAPI 3.0의 고정 속성 이름을 잘못 적거나 다른 객체에 배치하면 도구가 내용을 무시하거나 문서를 거부할 수 있습니다. 확장이 허용된 위치의 x- 속성과 스키마의 사용자 정의 데이터 필드 이름은 구분해야 합니다.

잠재적 영향

설명이나 계약 정보가 문서에서 누락되거나 클라이언트 생성과 검증이 실패할 수 있습니다.

해결 방법

사용 중인 OpenAPI 버전과 객체 정의에 맞춰 속성의 철자, 대소문자와 위치를 확인하세요. 확장이 필요한 경우 허용된 위치에서 x- 이름을 사용하고 소비 도구의 지원 여부를 확인하세요. 실제 데이터 필드 이름을 문서의 고정 속성으로 오해해 변경하지 마세요.

예시

응답과 태그의 description 철자를 비교하는 발췌입니다. 참조한 exampleSecurity의 보안 스킴 정의는 여기서 생략했습니다.

변경 전

json

{
  "openapi": "3.0.0",
  "info": {
    "title": "Simple API Overview",
    "version": "1.0.0"
  },
  "paths": {
    "/": {
      "get": {
        "operationId": "listVersionsv2",
        "summary": "List API versions",
        "responses": {
          "200": {
            "descrinnption": "200 response"
          }
        }
      }
    }
  },
  "security": [
    {
      "exampleSecurity": []
    }
  ],
  "tags": [
    {
      "name": "pets",
      "desdddcription": "Everything about your Pets",
      "externalDocs": {
        "url": "http://docs.my-api.com/pet-operations.htm"
      }
    },
    {
      "name": "store",
      "description": "Access to Petstore orders",
      "externalDocs": {
        "url": "http://docs.my-api.com/store-orders.htm"
      }
    }
  ]
}

변경 후

json

{
  "openapi": "3.0.0",
  "info": {
    "title": "Simple API Overview",
    "version": "1.0.0"
  },
  "paths": {
    "/": {
      "get": {
        "operationId": "listVersionsv2",
        "summary": "List API versions",
        "responses": {
          "200": {
            "description": "200 response"
          }
        }
      }
    }
  },
  "security": [
    {
      "exampleSecurity": []
    }
  ],
  "tags": [
    {
      "name": "pets",
      "description": "Everything about your Pets",
      "externalDocs": {
        "url": "http://docs.my-api.com/pet-operations.htm"
      }
    },
    {
      "name": "store",
      "description": "Access to Petstore orders",
      "externalDocs": {
        "url": "http://docs.my-api.com/store-orders.htm"
      }
    }
  ]
}

변경 전의 descrinnption과 desdddcription을 각각 description으로 수정합니다. API가 반환하는 데이터 구조를 변경하는 예시는 아닙니다.