안녕하세요. MOEUM에서 Software Engineer로 참여하고 있는 정승덕입니다 😃

오늘은 저희 팀에서 API 연동 자동화를 위해 OAS codegen을 도입한 경험을 공유드려요.

문제상황과 도입 방법, 결과를 기본으로 작성했어요.

저의 경험이 여러분들에게 도움이 될 수 있기를 바랍니다.

---

문제 상황

Backend Engineer분들께서 Swagger로 API 문서를 작성하면 Frontend Engineer분들이 그걸 보면서 필요한 타입과 API 함수를 직접 만들어서 사용했어요.

하지만 시간이 지날수록 이 방식의 문제점이 드러났는데요. 크게 두 가지가 있었어요.

먼저 API 스펙이 변경될 때마다 프론트엔드 개발자가 수동으로 코드를 수정해야 했어요. 이 과정에서 휴먼에러 및 동기화 문제가 일어나기도 했어요.

두번째는 쓰는 단어가 다르기도 했어요. 예를 들어 회원가입을 register라고 부르는 사람이 있는 반면, signup이라고 부르는 것처럼 말이에요.

이런 문제들을 겪다 보니 "이걸 좀 더 효율적으로 할 수 있는 방법이 없을까?" 하는 고민이 커졌고, 결국 API 연동 프로세스를 자동화해보기로 했어요.

---

기존 방식

1. 백엔드 개발자가 Swagger로 API 문서 작성

2. 프론트엔드 개발자가 Swagger 문서 참고하여:
   • Interface 타입 수동 정의
   • axios 요청 함수 수동 작성
   • API 응답 타입 수동 정의
3. API 스펙 변경 시 위 과정을 반복

이러한 수동 프로세스는 시간이 많이 소요되고 휴먼 에러가 발생하기 쉬웠습니다.

---

도입 방법

프로세스

• Backend: API 문서 변경사항을 Frontend 레포지토리에 PR로 전달

• Frontend: API 클라이언트 코드 생성하는 PR 테스트 후 머지

Backend to Frontend

참고파일: checkmate-backend/.github/workflows/oas.yml at develop · team-moeum/checkmate-backend · GitHub

Target Repository 설정

env:
  TARGET_REPO: team-moeum/checkmate-frontend                             # 프론트엔드 레포지토리
  TARGET_BRANCH: main                                                    # 대상 브랜치
  SOURCE_BRANCH: oas-${{ github.run_number }}-${{ github.run_attempt }}  # 생성될 브랜치
  API_DOCS_URL: ${{ secrets.API_DOCS_URL }}                              # API DOCS URL(<http://localhost:3000/v3/api-docs>)
  PERSONAL_ACCESS_TOKEN: ${{ secrets.PERSONAL_ACCESS_TOKEN }}            # repo, workflow 권한 TOKEN

Pull Request 생성

steps:
  - name: Create Pull Request
    run: |
      cd target-repo

      # Git 설정
      git config --local user.email "moeum[bot]@users.noreply.github.com"
      git config --local user.name "moeum[bot]"

      # 브랜치 생성 및 문서 복사
      git checkout -b $SOURCE_BRANCH
      cp ../swagger.json ./docs/api-doc.json

      # 커밋 및 푸시
      git add docs/api-doc.json
      git commit -m "Update API documentation"
      git push origin $SOURCE_BRANCH

      # PR 생성
      curl -X POST \\
        -H "Authorization: token $PERSONAL_ACCESS_TOKEN" \\
        -H "Accept: application/vnd.github.v3+json" \\
        <https://api.github.com/repos/$TARGET_REPO/pulls> \\
        -d '{
          "title": "Update API Documentation",
          "body": "Automatically generated API documentation update",
          "head": "'$SOURCE_BRANCH'",
          "base": "'$TARGET_BRANCH'"
        }'

Frontend API 생성

참고파일: checkmate-frontend/.github/workflows/oas.yml at main · team-moeum/checkmate-frontend · GitHub

workflow

on:
  pull_request:
    types: [opened, synchronize]
    paths:
      - "docs/api-doc.json" # API 문서가 업데이트될 때만 실행
    branches:
      - main

jobs:
  generate-api:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      ...
      - name: Generate documentation
        run: pnpm run generate
      ...

API 클라이언트 생성 스크립트

{
  "scripts": {
    "generate": "openapi-generator-cli generate -g typescript-axios -i ./docs/api-doc.json -o ./src.shared/apis -c ./openapi.json",
  }
}

---

결론

아래와 같이 프로세스를 개선하면서 자동화할 수 있었고 도입과정에서 나왔던 문제 대부분을 해결할 수 있었습니다.

다만, 앞으로 사용하는 과정에서 문제가 발생한다면 그 문제를 해결해나가는 과정도 기록해보려 합니다.

---

참고문서

• How to use OAS generator in Front-end environment? | hmos.dev

• Hello from OpenAPI Generator | OpenAPI Generator

• Documentation for the typescript-axios Generator | OpenAPI Generator

• GitHub Actions documentation - GitHub Docs

• 예시 PR: Update Swagger JSON by seungdeok · Pull Request #7 · team-moeum/checkmate-frontend · GitHub