OpenAPI Generator

👋 들어가기 전

이전 시간에 학습했던 OAS를 기반으로, OpenAPI Generator를 이용해서, API 작업에서 발생하는

반복적인 동작을 효율적으로 줄여보는 경험을 한번 해보자.

 

https://hamp.tistory.com/231

 

이전에 배웠던 내용을 정리하면 OAS는 결국 API 명세서를 .json 또는 .yaml 파일 형태로 제공해준다.

그러면 우리는 제공해주는 파일을 기준으로 .swift 파일을 받아야한다.

 

이 역할을 하는 것이 바로 OpenAPI Generator다.

 

앗 이러면 우리는 Swagger도 만들어야해 ??? 

아니다. 연습용으로 제공해주는 링크가 있다.

 

https://petstore.swagger.io

 

여기서 흥미로운점은 swgger링크 뒤에 /OAS버전/swggaer.(json 또는 yaml)을 적으면 OAS 내용을 볼 수 있다.

 

꼭, swagger.json이 아닐 수 있음, 백엔드 개발자가 제공하기 나름이다.

 

 

우리는 위 링크를 기반으로 generator를 돌려보자.

---

🏁 학습할 내용

• OpenAPIGenerator란
  • 왜 쓸까? 
  • 불편한 점
• 사용법
  • 설치
  • 준비
  • 실행
  • 결과
• 커스텀
  • 템플릿 다운로드
  • 사용
• 직접 느낀 불편함과 개선방법

---

✅ OpenAPI Generator란?

OpenAPI Generator는 API 명세서(OpenAPI Specification, OAS)를 기반으로 다양한
클라이언트 SDK, 서버 스텁, API 문서 등을 자동으로 생성해주는 오픈소스 도구

🙋 왜 쓸까?

클라이언트 입장에서 백엔드 API마다 반복적으로 하는 작업을 아래 그림으로 살펴보자.

• 수동으로 API 클라이언트를 만들 필요 없이 자동 생성 (클라이언트 쪽 휴먼 에러 감소)
• API 명세가 바뀌면 코드도 자동 갱신 가능 ➡️ 유지보수 효율 ⬆️
• 일관된 코딩 스타일 유지
• 프론트엔드와 백엔드 간의 협업이 수월해짐

개인적으로 백엔드 개발자분들께 죄송하지만, 명세서 기반으로 만들꺼니깐, 명세서 작성 잘 해주세요!
라는 무언의 압박을 주는 도구인 것 같다.

😭 불편한 점?

1️⃣ API 문서는 정확해야한다.

 

클라이언트 입장에서 휴먼에러가 대폭 감소하지만, 백엔드의 휴먼에러는 그대로 남아있기 때문에

무엇보다 정확한 명세서를 필수적인 전제조건이 되야한다.

 

2️⃣ 파일이 많아진다.

 

정해진 템플릿 형태로 결과들을 제공하기 때문에 그 과정에서 중복되는 코드들이 많아질 수도 있고

그 에 따른 서비스 Size가 커질 수 있다.

 

3️⃣ 초기 러닝커브 및 유지보수.

 

초기 설정이 굉장히 복잡하고, 우리 프로젝트에 맞게 커스텀이 들어가야한다.

그렇기 때문에 초기 러닝커브가 많이 높다.

 

또한 서비스 흐름에 따라 지속적으로 유지보수가 필요하다.

 

4️⃣ 버전 관리 및 컨플릭트

 

이 부분은 개인적인 경험에서 느꼈던 건데, 어느 시점에 generator를 돌릴 지 고민이된다.

프로젝트에서 나만 쓰면 상관이 없는데, 팀원이 있을 때, 내가 돌리고, 팀원이 돌리면

 

버전 관리가 필요하다, 또한 제너레이트 시점에 따른 컨플릭트가 발생할 수 있다.

 

불편한 점은 사용하면서 개선 방법을 추가해보자.

---

📋 사용법

⬇️ 설치

제너레이터 설치

brew install openapi-generator

☕️ 자바 설치

generator가 Java 기반이라 Java 설치 필요

brew install openjdk

✅ 설치 확인

openapi-generator version

🏋️  준비

🤟 .ymal 파일

먼저 generator에 사용될 메타 데이터인 ymal 파일을 받아야한다.

 

아래 스크립트를 통해 간편히 받을 수 있다.

#!/bin/bash

# 저장할 파일 이름
OUTPUT_FILE="data.yaml"

# 다운로드할 URL
URL="https://petstore.swagger.io/v2/swagger.yaml"

# curl을 사용하여 파일 다운로드
curl -o "$OUTPUT_FILE" "$URL"

# 결과 확인 메시지
if [ $? -eq 0 ]; then
  echo "✅ swagger.yaml 파일이 성공적으로 다운로드되었습니다."
else
  echo "❌ 다운로드 중 오류가 발생했습니다."
fi

▶️ 실행

이제 실행해보자.

아래 공식문서를 들어가면 실행할 때, 내가 줄 수 있는 옵션들을 모아놨다.

Documentation for the swift5 Generator | OpenAPI Generator

사용법은 아래 링크를 참고하자.

Configuration Options | OpenAPI Generator

 

나는 다음과 같은 조건으로 generator를 돌릴꺼다.

• data.ymal 사용
• swif5 사용
• 결과 코드는 GeneratedAPI라는 폴더를 생성
• alamofire 라이브러리를 기본으로 사용(default는 URLSesstion)

openapi-generator generate \
  -i data.yaml \
  -g swift5 \
  -o GeneratedAPI \
  --additional-properties=library=alamofire

 

여기서 만약 --additional-properties를 여러게 쓰면 스크립트가 복잡해지기때문에

config.json와 -c 옵션을 통해 동일한 형태의 옵션을 줄 수 있다.

// config.json
{
    "library": "alamofire"
}

openapi-generator generate \
  -i data.yaml \
  -g swift5 \
  -o GeneratedAPI \
  -c config.json

📦 결과

결과는 Package 형태로 받는다.

 

구조는 다음과 같다.

• docs: 각 API를 README.md 형태로 설명
• OpenAPIClient: 설정한 옵션으로 생선된 swift 코드

---

📑 커스텀하기

⬇️ 설치

먼저 우리 상황에 맞는 template을 받아야한다.

author template 명령어를 이용

-g: generator 옵션 

-o: 템플릿 저장될 장소

openapi-generator author template -g swift5 -o ./template

🥸 결과

결과는 콧수염 형태다. mustache... 처음 보는 확장자다.

 

내용만 살짝 보자. 흠.. 얼마전에 본 XCTemplate과 비슷한 형태다.

.xctemplate

결국 커스텀을 할려면 저 친구를 파악하고 나의 상황에 맞게 건드려야할 듯...

📑 템플릿 사용

위에서 사용했던 커맨드에 -t 옵션에 위에서 만든 template 경로를 지정해주면 끝 !

openapi-generator generate \
  -i data.yaml \
  -g swift5 \
  -o GeneratedAPI \
  -c config.json \
  -t template/

---

😡 직접 느낀 불편함과 개선방법

사용하면서 느낀 점과 개선점을 함께 추후 올리도록 하겠다.

---

😀 소감 및 마무리

자.. 틈틈히 정리해봤다.. 실제로 써보고 팀원들의 리뷰를 남길 수 있으면 첨부해보겠다.

---

출처

https://github.com/OpenAPITools/openapi-generator

GitHub - OpenAPITools/openapi-generator: OpenAPI Generator allows generation of API client libraries (SDK generation), server st

https://hmos.dev/how-to-use-oas-generator

Front-end에서 OAS generator를 어떻게 쓰면 좋을까? | hmos.dev

https://openapi-generator.tech

Hello from OpenAPI Generator | OpenAPI Generator