Swagger를 github page로 배포하기

JaeKyung Hwang·2024년 8월 25일

Swagger api document github actions github pages workflow

TECH

목록 보기

9/16

swagger-github-pages를 참고해 사용된 GitHub Actions workflow를 분석하고 swagger를 github page로 배포하는 방법에 대해 알아보자. https://github.com/do0ori/swagger-github-pages에서도 정리된 내용을 확인할 수 있다.

🧐 GitHub Actions workflow 분석해보기

The template will periodically auto-update the Swagger UI dependency and create a pull request.
See the GitHub Actions workflow here.

이 GitHub Actions workflow는 Swagger UI의 최신 release를 자동으로 업데이트하고 변경 사항을 PR로 생성하는 작업을 수행한다.

1. Trigger 조건

on:
  schedule:
    - cron: "0 10 * * *" # 매일 오전 10시에 실행
  workflow_dispatch: # 수동으로 실행할 수 있는 옵션

schedule: 매일 오전 10:00 UTC에 이 workflow가 자동으로 실행된다. (GitHub Actions schedule 관련 참고 자료)
workflow_dispatch: GitHub interface를 통해 수동으로 이 workflow를 실행할 수 있다. (GitHub Actions workflow_dispatch 관련 참고 자료)

2. Job 정의

jobs:
  updateSwagger:
    runs-on: ubuntu-latest

job의 이름은 updateSwagger이고 최신 Ubuntu 이미지를 사용하여 실행된다.

3. Steps

a. 코드 checkout

steps:
  - uses: actions/checkout@v4

리포지토리의 코드를 앞서 생성된 Ubuntu 가상 머신의 작업 디렉토리로 복사한다.
이제 모든 코드 작업은 여기서 이루어진다.

b. 최신 Swagger UI Release 가져오기

- name: Get Latest Swagger UI Release
  id: swagger-ui
  run: |
    release_tag=$(curl -sL https://api.github.com/repos/swagger-api/swagger-ui/releases/latest | jq -r ".tag_name")
    echo "release_tag=$release_tag" >> $GITHUB_OUTPUT
    current_tag=$(<swagger-ui.version)
    echo "current_tag=$current_tag" >> $GITHUB_OUTPUT

최신 Swagger UI release tag를 가져와 release_tag 변수에 저장한다.
swagger-ui.version 파일에서 현재 사용 중인 release tag를 읽어 current_tag 변수에 저장한다.

c. Swagger UI 업데이트

- name: Update Swagger UI
  if: steps.swagger-ui.outputs.current_tag != steps.swagger-ui.outputs.release_tag
  env:
    RELEASE_TAG: ${{ steps.swagger-ui.outputs.release_tag }}
    SWAGGER_YAML: "swagger.yaml"
  run: |
    rm -fr dist index.html
    curl -sL -o $RELEASE_TAG https://api.github.com/repos/swagger-api/swagger-ui/tarball/$RELEASE_TAG
    tar -xzf $RELEASE_TAG --strip-components=1 $(tar -tzf $RELEASE_TAG | head -1 | cut -f1 -d"/")/dist
    rm $RELEASE_TAG
    mv dist/index.html .
    sed -i "s|https://petstore.swagger.io/v2/swagger.json|$SWAGGER_YAML|g" dist/swagger-initializer.js
    sed -i "s|href=\"./|href=\"dist/|g" index.html
    sed -i "s|src=\"./|src=\"dist/|g" index.html
    sed -i "s|href=\"index|href=\"dist/index|g" index.html
    echo ${{ steps.swagger-ui.outputs.release_tag }} > swagger-ui.version

최신 release tag(release_tag)와 현재 사용 중인 tag(current_tag)가 다를 경우 실행된다.
dist 디렉토리와 index.html 파일을 삭제한다.
최신 release를 다운로드하고 압축 해제하여 dist 디렉토리를 추출한다.
dist/index.html을 root 디렉토리로 옮긴다.
dist/swagger-initializer.js와 index.html 파일의 경로와 참조를 수정한다.
새로운 release tag(release_tag)를 swagger-ui.version 파일에 저장한다.

d. Pull Request 생성

- name: Create Pull Request
  uses: peter-evans/create-pull-request@v6
  with:
    commit-message: Update swagger-ui to ${{ steps.swagger-ui.outputs.release_tag }}
    title: Update SwaggerUI to ${{ steps.swagger-ui.outputs.release_tag }}
    body: |
      Updates [swagger-ui][1] to ${{ steps.swagger-ui.outputs.release_tag }}

      Auto-generated by [create-pull-request][2]

      [1]: https://github.com/swagger-api/swagger-ui
      [2]: https://github.com/peter-evans/create-pull-request
    labels: dependencies, automated pr
    branch: swagger-ui-updates

peter-evans/create-pull-request action을 사용하여 Swagger UI의 최신 release로 업데이트하는 PR을 생성한다.
commit message, PR 제목, 본문, label 등을 설정한다.
swagger-ui-updates라는 이름의 branch에서 PR을 생성한다.

🚀 리포지토리에 적용해보기

이 리포지토리의 .github, dist, index.html, swagger-ui.version을 내 리포지토리로 옮기기

dist/swagger-initializer.js 파일의 url 속성을 내 swagger yaml file 경로로 수정

    window.ui = SwaggerUIBundle({
        url: "swagger.yaml",
    ...

.github/workflows/update-swagger.yml 파일의 SWAGGER_YAML env 값을 내 swagger yaml file 경로로 수정
```
env:
  RELEASE_TAG: ${{ steps.swagger-ui.outputs.release_tag }}
  SWAGGER_YAML: "swagger.yaml"
```
⚠️ 기존에 있던 다른 workflow들의 동작을 고려하여 적당한 수정이 필요할 수 있음
리포지토리에서 Settings > Pages > Branch를 main으로 설정하고 Save해서 GitHub Pages를 활성화시키기
https://{github-username}.github.io/{repository-name}로 이동하여 Swagger 문서 확인하기

나의 경우 https://do0ori.github.io/swagger-github-pages에 hosting되어 있다.

그냥 가져다가 쓸 수도 있지만 이 참에 GitHub Actions workflow도 분석해보며 어떻게 동작하는 것인지 알아보았다. 어떤 방식으로 github pages에 swagger를 배포할 수 있는지 이해할 수 있었다. 댕댕워크 프로젝트의 swagger도 이 방식으로 배포했다.