Swagger Validator 역할과 문제 해결

[Tae4an]

🔍 Swagger Validator란?

Swagger Validator는 OpenAPI/Swagger 스펙 파일의 유효성을 검증하는 외부 서비스다.

주요 역할:

1. 스펙 유효성 검증: OpenAPI 3.0/Swagger 2.0 문법 검사
2. 시각적 피드백: 스펙이 유효하면 녹색 체크마크, 오류가 있으면 빨간색 X 표시
3. 실시간 검증: Swagger UI 로드 시 자동으로 스펙 파일을 검증

작동 방식:

Swagger UI → <https://validator.swagger.io/validator?url=YOUR_SPEC_URL> → 검증 결과 이미지 반환

❌ 발생했던 문제들

1. CSP(Content Security Policy) 위반

Refused to load the image '<https://validator.swagger.io/validator?url=>...'
because it violates the following Content Security Policy directive: "img-src 'self' data:"

원인: Kong에서 설정한 CSP가 외부 이미지 로드를 차단

• img-src 'self' data: → 자체 도메인과 data: URL만 허용
• validator.swagger.io는 외부 도메인이라 차단됨

2. 404 에러

/swagger-specs/auth-service.json:1 Failed to load resource: the server responded with a status of 404

원인: Kong에서 정적 웹 서버로의 라우팅 실패

• Kong 설정에서 http://haptitalk-static-web:80 사용
• 실제 Docker 네트워크에서는 http://static-web:80이 올바른 주소

✅ 해결 방법과 이유

방법 1: CSP 수정 (부분적 해결)

# 기존
img-src 'self' data:

# 수정 후
img-src 'self' data: <https://validator.swagger.io>

효과: Validator 이미지 로드 허용, 하지만 외부 의존성 증가

방법 2: Validator 비활성화 (권장 해결책)

SwaggerUIBundle({
  // ... 기타 설정
  validatorUrl: null,  // ← 이 설정으로 validator 완전 비활성화
})

왜 이 방법이 더 좋은가?

1. 외부 의존성 제거: 인터넷 연결이나 외부 서비스에 의존하지 않음
2. 보안 강화: 외부로 스펙 URL이 전송되지 않음
3. 성능 향상: 외부 API 호출 없어서 로딩 속도 개선
4. 프라이버시 보호: 내부 API 스펙 정보가 외부로 노출되지 않음

방법 3: 라우팅 수정

# 기존 (잘못된 설정)
url: <http://haptitalk-static-web:80>

# 수정 후 (올바른 설정)
url: <http://static-web:80>

이유: Docker Compose에서 서비스 이름은 static-web이지만, 컨테이너 이름은 haptitalk-static-web

📊 문제 해결 요약

문제	원인	해결책	효과
CSP 위반	외부 validator 이미지 차단	validatorUrl: null	외부 요청 완전 차단
404 에러	잘못된 서비스 URL	static-web:80 사용	정적 파일 정상 로드
보안 우려	외부 서비스 의존	Validator 비활성화	내부 정보 보호

최종 결과

변경 전:

❌ CSP 위반으로 validator 이미지 로드 실패
❌ 404 에러로 swagger-specs 파일 로드 실패
❌ 외부 서비스 의존성으로 보안 위험

변경 후:

✅ Validator 비활성화로 외부 요청 없음
✅ 올바른 라우팅으로 스펙 파일 정상 로드
✅ 완전한 내부 서비스로 보안 강화
✅ 빠른 로딩 속도와 안정적인 서비스