Swagger-UI, 개발 환경에서만 노출하고 운영 환경에서는 숨기는 방법: 상세 가이드

Swagger-UI는 개발 과정에서 API 문서를 시각적으로 확인하고 테스트하기에 매우 유용한 도구입니다. 하지만, 운영 환경에서는 보안상의 이유로 민감한 정보가 노출될 수 있으므로, Swagger-UI를 숨기는 것이 일반적입니다. 이 글에서는 Swagger-UI를 개발 환경에서만 노출하고, 운영 환경에서는 숨기는 방법을 다양한 관점에서 자세히 설명합니다.

왜 Swagger-UI를 숨겨야 할까요?

• 보안: Swagger-UI는 API에 대한 모든 정보를 제공하기 때문에, 악의적인 사용자가 이를 이용해 시스템을 공격할 수 있습니다. 특히, API 엔드포인트, 요청/응답 데이터 형식, 인증 방식 등 민감한 정보가 노출될 수 있습니다.
• 성능: Swagger-UI는 API 문서를 생성하고 제공하는 데 추가적인 자원을 소모합니다. 운영 환경에서는 불필요한 자원 낭비를 줄여야 합니다.
• 복잡성: Swagger-UI는 개발 환경에서 주로 사용되므로, 운영 환경에서는 관리해야 할 구성 요소가 하나 줄어듭니다.

728x90

Swagger-UI 숨기는 방법

1. 프로파일 기반 설정

• Spring Boot: application.properties 또는 application.yml 파일에서 프로파일을 설정하고, 각 프로파일별로 Swagger-UI 활성화 여부를 다르게 설정합니다.
   

  # application.properties
  springdoc.api-docs.enabled=${enable.swagger}
  

   

  # application.yml
  springdoc:
    api-docs:
      enabled: ${enable.swagger}
  

• 다른 프레임워크: 사용하는 프레임워크의 설정 파일에서 Swagger-UI 관련 설정을 프로파일별로 관리합니다.

2. 빌드 시점 설정

• Maven: pom.xml 파일에서 프로파일을 설정하고, 각 프로파일별로 Swagger-UI 관련 의존성을 포함하거나 제외합니다.
• Gradle: build.gradle 파일에서 프로파일을 설정하고, 각 프로파일별로 Swagger-UI 관련 의존성을 포함하거나 제외합니다.

3. 코드 레벨 설정

• 조건문: 코드에서 if 문 등을 사용하여 개발 환경인지 운영 환경인지 판단하고, Swagger-UI 관련 코드를 실행하거나 건너뜁니다.
• AOP: Aspect Oriented Programming을 이용하여 Swagger-UI 관련 기능을 동적으로 제어합니다.

4. 배포 시 설정

• Docker: Dockerfile에서 ENV 변수를 설정하여 Swagger-UI 활성화 여부를 제어하고, Docker Compose를 이용하여 다양한 환경에 맞춰 배포합니다.
• Kubernetes: Kubernetes Manifest 파일에서 환경 변수를 설정하여 Swagger-UI 활성화 여부를 제어하고, Helm Chart 등을 이용하여 배포합니다.

추가적인 고려 사항

• 보안: Swagger-UI를 완전히 숨기더라도, API에 대한 정보가 유출될 가능성이 있습니다. API Gateway 등을 사용하여 API를 추가로 보호하는 것이 좋습니다.
• 테스트: 운영 환경에서 Swagger-UI를 비활성화한 후에도 API가 정상적으로 작동하는지 반드시 테스트해야 합니다.
• 문서화: Swagger-UI를 사용하지 않더라도, API 문서는 별도로 관리해야 합니다.

728x90

Swagger-UI는 개발 과정에서 매우 유용한 도구이지만, 운영 환경에서는 보안과 성능 문제를 야기할 수 있습니다. 따라서, 프로젝트의 특성과 요구사항에 맞춰 적절한 방법으로 Swagger-UI를 숨기는 것이 중요합니다. 위에서 설명한 다양한 방법들을 참고하여 프로젝트에 최적화된 설정을 적용해 보세요.

 

참고: 위 내용은 일반적인 가이드이며, 실제 적용 시에는 프로젝트의 구조와 사용하는 기술 스택에 따라 달라질 수 있습니다.