상대 서버 URL의 기준 주소 점검

설명

OpenAPI 3.0은 상대 서버 URL을 허용하며, OpenAPI 문서를 제공하는 위치를 기준으로 해석합니다. 상대 URL 자체는 오류가 아니지만 문서의 호스팅 위치가 바뀌면 의도와 다른 서버를 가리킬 수 있습니다.

잠재적 영향

문서 도구나 클라이언트가 잘못된 엔드포인트로 요청할 수 있습니다. 특히 호스트 이름처럼 보이는 경로를 실제 호스트 주소로 오해하지 않도록 주의해야 합니다.

해결 방법

상대 URL을 문서 제공 위치에 대해 해석한 결과가 의도한 주소인지 확인하세요. 문서 위치와 독립적인 서버를 지정하려면 HTTPS 스킴과 호스트를 포함한 절대 URL을 사용하세요.

예시

Link의 서버 URL을 비교하는 발췌이며 대상 작업의 operationId 또는 operationRef는 생략했습니다. 두 URL 형식 모두 허용되지만 같은 대상을 뜻하지 않습니다.

변경 전

json

{
  "openapi": "3.0.0",
  "info": {
    "title": "Simple API Overview",
    "version": "1.0.0"
  },
  "paths": {
    "/": {
      "get": {
        "summary": "List API versions",
        "responses": {
          "200": {
            "description": "the user being returned",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "uuid": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                }
              }
            },
            "links": {
              "address": {
                "server": {
                  "url": "/development.gigantic-server.com/v1"
                }
              }
            }
          }
        },
        "operationId": "listVersionsv2"
      }
    }
  }
}

변경 후