MSA 환경에서 서비스별 Swagger UI를 GitHub Pages로 배포하기

🔎 개요

개인프로젝트를 MSA구조로 설계하고 각 마이크로서비스마다 주요 기능 개발이 완료된 후, 개발한 API를 한 눈에 볼 수 있는 문서화 페이지가 필요했습니다.

Spring Boot와 우수한 호환성으로 기존 코드로 손쉽게 API 스펙을 정의할 수 있어서 Swagger를 선택했습니다

또한, 무료 정적 사이트 호스팅을 제공하고 Git 기반으로 쉽게 배포할 수 있어서 GitHub Pages를 사용했습니다

 

참고 블로그를 찾아보던 중 GitHub에 Swagger API 문서를 공유하기 글을 보게 되었고, 해당 내용을 바탕으로 구현했습니다

 

🛠️ 백엔드 환경 

각 마이크로서비스의 기술 스택은 다음과 같습니다

• Java : 17
• Spring Boot : 3.3.5
• Build Tool : Gradle
• API 문서화 : SpringDoc Open API 3

 

⚙️ 구현과정

Step 1: Spring Boot에 Swagger 설정

// swagger
implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.0.2'

각 마이크로서비스에 Swagger 의존성을 추가합니다.

 

Contorller 마다 `@Tag`와 `@Operation` 어노테이션을 사용해 API 설명을 작성했습니다

로컬에서 애플리케이션을 구동한 후 `http://localhost:8081/swagger-ui/index.html\`에 접속하여 Swagger UI가 정상적으로 동작하는지 확인합니다.

 

💡Tip : Swagger 접속경로는 url 뒤에 `/swagger-ui/index.html` 붙이면 됩니다

 

Step 2: swagger.json 파일 생성

• OpenAPI definition 아래에 있는 `/v3/api-docs` 링크를 클릭합니다

 

• JSON형식의 데이터가 보이면 전체 텍스트를 복사한 다음, Mac인 경우 텍스트편집기 Window인 경우 메모장을 사용해서 임의의 위치에 저장합니다 (이후에 파일 이동할 예정)
• 저는 마이크로서비스마다 아래와 같이 구분하여 저장했습니다
  • `oo-sms-sms-swagger.json` (SMS 서비스)
  • `oo-sms-cust-swagger.json` (고객 관리 서비스)
  • `oo-sms-booking-swagger.json` (예약 관리 서비스)

 

Step 3: GitHub Pages용 Swagger UI 준비

1. Swagger UI GitHub 레포지토리 Fork

• swagger-ui GitHub 레포지토리 에 접속합니다
• 상단 우측의 Fork 버튼 클릭하여 자신의 계정으로 복사합니다

2. 로컬 환경 설정

git clone [복사한 HTTPS URL]

# 예시
git clone https://github.com/Jisu-Shin/oo-sms-swagger-ui.git

• '<> Code' 초록 버튼을 눌러서 클론하기 위한 URL 주소를 복사합니다

 

3. dist 폴더를 루트 경로로 이동

• git clone 하여 로컬에서 확인할 수 있는 swagger-ui 폴더입니다. dist 폴더 내부의 모든 파일을 루트 경로로 이동합니다 (검정색으로 표시된 부분들)
• Step 2에서 저장한 json 파일도 루트 경로로 이동합니다. (빨간색으로 표시된 부분들)

4. GitHub에 변경 및 추가된 내용들 Push

   git add .
   git commit -m "Add swagger files for microservice"
   git push origin main

 

Step 4 : Swagger UI 설정 및 배포

1. swagger.json URL 설정

• GitHub로 push한 swagger.json 파일 클릭합니다 (보이는 이미지에서는 `oo-sms-sms-swagger.json` )
• "Raw" 버튼 클릭하여 직접 접근 URL 복사합니다 (빨간색 동그라미로 Raw 버튼 표시)

 

2. swagger-initializer.js 수정

• 8, 12, 16번째 라인의 URL부분에 Raw로 추출한 json url을 작성했습니다
• swagger-initializer.js 파일을 수정 후 commit 합니다

 

3. GitHub Pages 활성화

1. 레포지토리 설정에 들어갑니다
2. Pages 탭 클릭합니다
3. Branch를 master root로 설정하고 save 버튼을 누릅니다
4. GitHub Pages 활성화가 완료됩니다!

 

🚨 +) CORS 이슈 해결

@Configuration
public class SwaggerConfig implements WebMvcConfigurer {
    public void addCorsMappings(CorsRegistry registry) {
        registry.addMapping("/**")
                .allowedOrigins("http://localhost:8080")  // Swagger UI
                .allowedMethods("*")
                .allowedHeaders("*");
    }
}

 

GitHub Pages에서 로컬 API를 호출할 때 CORS 오류가 발생했습니다.

이를 해결하기 위해 각 마이크로서비스에 위와 같은 설정 클래스를 추가했습니다

 

🖥️ 결과 확인

위와 같이 여러 마이크로서비스의 API 문서들을 한 곳에서 통합하여 볼 수 있게 되었습니다.

각 서비스별로 탭을 전환하며 API 스펙을 확인할 수 있고, 실제로 API 호출 테스트도 가능합니다.

 

🌐 배포된 Swagger UI : https://jisu-shin.github.io/oo-sms-swagger-ui/

📂 관련 Github 레포지토리 : https://github.com/Jisu-Shin/oo-sms-swagger-ui

 

MSA 환경에서 API 문서 통합 관리가 필요하신 분들에게 도움이 되길 바랍니다.

 

📚 참고

• GitHub에 Swagger API 문서를 공유하기