스키마 외부 문서 URL 점검

설명

스키마의 externalDocs.url은 데이터 모델의 의미나 제약 조건을 설명하는 별도 문서를 연결합니다. 링크가 잘못되면 보충 정보를 확인하기 어렵습니다. OpenAPI 3.0의 상대 URL은 서버 URL을 기준으로 해석할 수 있습니다.

잠재적 영향

API 사용자가 필드의 업무 의미나 세부 제약을 놓쳐 데이터 처리와 연동에 오류가 생길 수 있습니다.

해결 방법

해당 스키마의 실제 설명 문서를 연결하고 주소와 내용을 확인하세요. 상대 링크는 기준 서버 주소에서 의도한 대상으로 해석되는지 확인하며, 별도 문서 사이트에는 명시적 URL을 사용할 수 있습니다.

예시

OpenAPI 3.0의 User 스키마에 상대 경로 /을 둔 경우와 문서 주소를 명시한 경우입니다. 상대 경로라는 이유만으로 잘못된 링크는 아닙니다.

변경 전

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"
                            }
                          ]
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "User": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "name": {
            "type": "string"
          }
        },
        "externalDocs": {
          "url": "/"
        }
      }
    }
  }
}

변경 후