Redoc을 통한 분산 서비스 통합 API 문서 배포 도전기

 

 

나는 원래 사용하던 서버의 API 명세서는 항상 springdoc 라이브러리를 이용하여 Swagger를 만들었었다.

 

 

분산 서비스 환경에서 Swagger를 이용한다면, 다음과 같이 서비스 당 URL이 생겨 필요한 명세서를 찾아 링크를 이리저리 옮겨다녀야 하는 상황이 생긴다.

 

 

이러한 문제를 인지하고 있다가, 운 좋게 라인 테크 블로그의 글을 보았다!

 

 

https://techblog.lycorp.co.jp/ko/api-document-integration-and-documentation-automation

모두가 행복해지는 API 문서 통합과 자동화

 

바로 프로젝트에 적용해 보아야겠다고 생각했다.

 

 

 

 

 

 

Github Pages

통합된 문서에 대한 페이지는 Github Pages를 이용하여 배포됐다.

 

Github Pages는 깃허브 레포의 정적인 웹사이트 이미지를 손쉽게 배포해주는 기능이다.

 

여러 블로그에서 봤던 도메인 형식인 ~~~.github.io 형식이다.

 

 

 

 

Redoc

 

문서 페이지 생성은 Redoc이라는 도구를 사용한다.

 

 

나는 평생 Swagger만 접해보았었는데, Redoc을 경험하는 좋은 기회로 삼고 도전해보기로 했다 !!

 

https://redocly.github.io/redoc/

ReDoc Interactive Demo

 

Redoc 명세서의 데모 사이트이다.

 

 

 

 

plugins {
    id 'java'
    id 'org.springframework.boot' version '3.2.3'
    id 'io.spring.dependency-management' version '1.1.4'
    id "org.springdoc.openapi-gradle-plugin" version '1.8.0'
}


//...



dependencies {
    //Springdoc
    implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.1.0'

}

 

 

gradle-plugin의 의존성을 추가해두면 gradle task를 통해 API 문서를 JSON 형태로 추출할 수 있다.

 

이를 위한 몇가지 build.gradle 설정을 내 서버에 맞게 적용해 보았다.

 

 

openApi {
    apiDocsUrl.set("http://localhost:8000") // Document URL
    outputDir.set(file("$rootDir/docs")) // Build Result Path
    outputFileName.set("noti.json") // Build Result File Name
    groupedApiMappings.set(Map.of("http://localhost:8082/noti/api-docs", "noti.json"))
    waitTimeInSeconds.set(60) // Timeout
    customBootRun {
        args.add("--spring.profiles.active=dev")
    }
}

 

본문의 $buildDir 은 Deprecate 되었다고 한다. $rootDir 로 바꿔주었다.

 

 

 

 

 

 

 

실행

 

 

gradle의 generateApiDocs Task를 실행하면 애플리케이션을 한 번 실행하게 된다.

 

openapi를 통해 만들어진 API 명세서를 추출해야 하기 때문이다.

 

그렇다면, 원래 같이 맞물려서 돌아갈 Spring Cloud Config , Eureka , Kakfa ... 가 켜져있어야 된다는 것이다.

 

1회성 실행이기 때문에 Eureka, Kafka는 필요없겠지만.. Config Server가 없으면 구동이 안됐다.

 

GitHub Action Runner는 가상환경이기 때문에, 이를 해결하려면 가상환경에서 구동해야 했다.

 

 

 

 

 

결과는 yml이 없으니 실패 ..

 

 

이런 쪽 지식이 없는 나는 혼란에 빠졌다..

 

1. 1회성 실행이니까 DataSource 를 Exclude하고 실행

직접 main함수에서 datasourceConfiguration을 exclude하는 방법. 동작될 수 있겠지만, 좋은 방법이 아니라고 생각

 

2. 1회성 application.yml을 주입

Github Action Secret을 통해 설정값을 주입하고 RDS에 연결하는 방법. RDS배포 상태가 아니라면 실행할 수 없음

 

3. Spring Cloud Config만 미리 배포해두고 Fetching 

Config Server배포 전 상태. 변수가 많아지고 오버헤드가 큼. 또한, 이미 배포한 상태라면 배포된 애플리케이션과 중복 접근이 일어날 수 있음

 

4. Github Runner에 Config Service를 가져와서

yml 저장소와 통신할 private key또한 추가로 설정이 필요함. 프로세스 또한 길어지고, 오버헤드가 큼

 

 

 

 

 

 

 

결국 그나마 2번을 선택해 Github Action Secret을 이용하여 1회성 bootstrap.yml 을 주입해보기로 결정했다.

 

 

 

60초 timeout

 

 

 

60초 Timeout 을 걸어놨던 것에서 걸렸다. 60초를 기다려도 받지 못한 것이다.

 

Kafka 서버에 토픽 생성, 구독, Eureka 서버 등록 시도 등등 서버 구축에 너무 오랜 시간이 걸린다.

 

 

 

물론 timeout을 길게 설정하면 되겠지만,

 

API 명세서를 위해 서버를 빌드하고 추출하는 과정은 너무 무겁다고 생각했다.

 

그래서 방법을 조금 바꾸기로 했다.

 

 

 

 

 

회선

 

 

gradle task를 통해 추출된 json 을 Github Action이 가져가서 생성하기로 했다.

 

API 스펙이 바뀌면 task를 로컬로 실행하기로 했다. API 스펙은 그렇게 많이 바뀌지 않으니..

 

일단 Github Pages를 배포할 레포를 만들었다.

 

 

 

 

 

 

<owner 이름>.github.io 이름으로 만들어야 한다.

 

$ ssh-keygen -t rsa -b 4096 -C "{email}"

 

ssh 키를 만들어준다.

 

여기서 중요한 점은, Deploy Key로 사용하려면 passphrase를 설정하지 않는것이 좋다.

 

 

https://github.com/marketplace/actions/webfactory-ssh-agent

 

ssh-agent를 만든 webfactory에서 '어차피 private key는 Secret에 저장되니 안전할 것이고, passphrase를 Input으로 넣지 않아도 실행되어야 하기 때문이다.' 라고 한다.

 

실제로 passphrase가 있는 키를 넣으면 input을 요구하고, 없다면 Action이 실패한다.

 

 

 

 

레포에 public key를 Deploy Key로 등록해준다.

 

이제 본 레포의 github action 스크립트를 작성한다.

 

name: API Docs Integration

on:
  push:
    branches:
      - develop

jobs:
  api-docs-integration:
    runs-on: ubuntu-latest
    steps:

      # 프로젝트 코드 가져오기
      - name: Checkout Code 
        uses: actions/checkout@v3
        with:
          ref: 'develop'

      # Json 파일 가져오기
      - name : collect json
        run : |
            cp ./noti-service/docs/noti.json ./
            cp ./user-service/docs/user.json ./
            cp ./weather-service/docs/weather.json ./

      # [Redoc] json 파일 join
      - name: redoc-cli join
        uses: DeltaLaboratory/redocly-cli-action@v1.0.0
        with:
          args: 'join *.json -o api.yaml'

      - name: check result
        run: |
          ls -al
          test -f api.yaml || (echo "Missing api.yaml from previous step." && exit 1)
      
      # [Redoc] Build docs
      - name: redoc-cli build docs
        uses: DeltaLaboratory/redocly-cli-action@v1.0.0
        with:
          args: 'build-docs api.yaml -o index.html'

      - name: check result
        run: |
          ls -al
          test -f index.html || (echo "Missing index.html from previous step." && exit 1)
          
      # 웹페이지 Repository에 Push
      - name: Install SSH Key
        uses: leigholiver/commit-with-deploy-key@v1.0.4
        with:
          source: index.html
          destination_folder: docs
          destination_repo: WaitherTeam/WaitherTeam.github.io
          destination_branch: main
          deploy_key: ${{ secrets.DEPLOY_KEY }}

 

Redoc-cli

 

처음에는 Marketplace의 star가 가장 많은 위에 있는걸 이용했는데, 

계속 실패를 거듭했다.

 

수정하고 실행하고 수정하고 실행하고

 

스크립트를 잘못 썼는지, args를 잘 못 전달했는지 계속해서 확인하고 수정하고를 반복했다.

 

직접 라이브러리를 뜯어보니 도커 이미지를 가져와서 redoc-cli를 arg를 전달하여 실행하는 듯 했다.

 

도커 내에서 작동하다 보니 로그도 보이지 않고 답답했다 🫠

 

The join command is considered an experimental feature

https://redocly.com/docs/cli/commands/join/

join

 

직접 Redoc 라이브러리를 찾아가서 join 명령어를 보았는데, join이 실험적 기능...?

 

그래도 로컬에서 직접 실행해보니, 작동하지 않는 것이 아니다.

 

여기서 논리적 추론으로.. join이 실험적 기능이라는 뜻은 개발된지 얼마 되지 않았다..? 버전이 맞지 않나? 라는 생각이 들었다.

 

그래서 직접 라이브러리 커밋을 봤더니.. 4년전 ..🤔 버전이 맞지 않는게 분명하다.

 

그래서 그나마 최근인 DeltaLaboratory/redocly-cli-action@v1.0.0 으로 바꾸었더니 바로 동작했다.. 🥲

 

[교훈]

 

1. 로그는 정말 소중하다.

 

2. 버전 확인도 정말 중요하다.

 

3. 정보가 없다면 논리적 추론 능력을 발휘해라.

 

 

 

Github Push

 

라인 블로그에선 개인 Runner를 이용하여 지정한 듯 했다.

 

그래서 나는 따로 레포 접근 권한을 구축해야 했다.

 

처음에는 deploy key 말고 access token으로 해보려 했지만 올가니제이션이라 그런지 여러 설정을 만져봐도 403을 받을 뿐이었다.

 

결국 Deploy Key를 등록하고 , Marketplace에서 검색해서 다음을 사용했다.

leigholiver/commit-with-deploy-key@v1.0.4

 

 

 

 

 

 

 

 

 

이렇게 해두고 웹페이지 설정에서 Pages를 활성화해주면 ..

 

배포가 완료된다 !! ......

 

 

 

 

 

 

 

 

 

 

 

 

시행착오.jpg