전역 외부 문서 URL 점검

설명

최상위 externalDocs.url은 API 전체와 관련된 추가 문서로 연결됩니다. 주소 오류나 의도하지 않은 대상은 사용자의 이해를 방해합니다. OpenAPI 3.0에서는 서버 URL을 기준으로 해석하는 상대 참조도 허용합니다.

잠재적 영향

사용자가 운영 가이드나 상세 설명을 찾지 못해 API 사용과 문제 해결에 시간이 더 걸릴 수 있습니다.

해결 방법

API 전체에 해당하는 실제 문서 주소를 지정하고 링크를 확인하세요. 상대 URL이라면 기준 서버 주소에서 올바르게 해석되는지 확인하고, 문서가 별도 사이트에 있다면 절대 URL을 사용하세요.

예시

OpenAPI 3.0에서 /과 외부 사이트의 문서 URL을 비교합니다. /은 유효한 상대 참조일 수 있으므로 실제 연결 대상과 목적이 맞는지가 중요합니다.

변경 전

json

{
  "openapi": "3.0.0",
  "info": {
    "title": "Simple API Overview",
    "version": "1.0.0",
    "contact": {
      "name": "contact",
      "url": "https://www.google.com/",
      "email": "user@gmail.com"
    }
  },
  "paths": {
    "/": {
      "get": {
        "operationId": "listVersionsv2",
        "summary": "List API versions",
        "responses": {
          "200": {
            "description": "200 response",
            "content": {
              "application/json": {
                "examples": {
                  "foo": {
                    "value": {
                      "versions": [
                        {
                          "status": "CURRENT",
                          "updated": "2011-01-21T11:33:21Z",
                          "id": "v2.0",
                          "links": [
                            {
                              "href": "http://127.0.0.1:8774/v2/",
                              "rel": "self"
                            }
                          ]
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "externalDocs": {
    "url": "/"
  }
}

변경 후

json

{
  "openapi": "3.0.0",
  "info": {
    "title": "Simple API Overview",
    "version": "1.0.0",
    "contact": {
      "name": "contact",
      "url": "https://www.google.com/",
      "email": "user@gmail.com"
    }
  },
  "paths": {
    "/": {
      "get": {
        "operationId": "listVersionsv2",
        "summary": "List API versions",
        "responses": {
          "200": {
            "description": "200 response",
            "content": {
              "application/json": {
                "examples": {
                  "foo": {
                    "value": {
                      "versions": [
                        {
                          "status": "CURRENT",
                          "updated": "2011-01-21T11:33:21Z",
                          "id": "v2.0",
                          "links": [
                            {
                              "href": "http://127.0.0.1:8774/v2/",
                              "rel": "self"
                            }
                          ]
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "externalDocs": {
    "url": "http://docs.my-api.com/store-orders.htm"
  }
}

변경 후에는 특정 문서 페이지를 명시합니다. 예시의 주소를 실제 API 전체에 관한 문서로 바꾸고 내용과 접근 가능 여부를 확인하세요.