작업별 외부 문서 URL 점검

설명

작업 수준의 externalDocs.url은 해당 API 호출에 대한 상세 문서로 연결됩니다. 잘못된 주소나 무관한 자료는 작업의 세부 규칙을 이해하기 어렵게 만듭니다. OpenAPI 3.0에서는 상대 URL도 서버 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",
        "externalDocs": {
          "url": "/"
        },
        "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"
                            }
                          ]
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

변경 후

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",
        "externalDocs": {
          "url": "http://docs.my-api.com/store-orders.htm"
        },
        "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"
                            }
                          ]
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

변경 후에는 문서 페이지가 명시됩니다. 실제로 해당 작업을 설명하는 자료인지 확인하고 예시 주소를 교체하세요.