HomeBuilder의 OpenAPI Generator 도입기

안녕하세요! SmartStudio HomeBuilder 팀에서 개발을 담당하고 있는 주니어 개발자 장우영입니다. 저희 팀은 올해 1월부터 Samanda Project를 시작하면서 신기술 및 다양한 변화를 도입해 Software Quality를 높이는 활동을 하고 있습니다. 자바스크립트를 활용하여 FE + BE 개발을 진행하다 보니 각 분야별 경계가 사라지고 이 과정 속에서 어떻게 하면 효율적으로 FE 개발자와 BE 개발자가 좋은 시너지를 만들 수 있을까라는 고민을 하게 되었습니다. 이 고민과 함께 API 개발과정에서 발생하는 여러 가지 문제를 맞닥뜨렸고 이를 해결하기 위해 도입했던 OpenAPI Generator에 대해 소개하고자 합니다. 

API 개발 과정에서 겪었던 문제점

API 개발 과정에서 발생했던 문제점은 바로 커뮤니케이션 비용입니다. FE 개발자가 개발된 API와 통신을 하기 위해서는 API에 대한 정확한 스펙을 알고 있어야 합니다. 이 과정에서 스펙을 확인하기 위한 여러 커뮤니케이션 비용이 생깁니다.

  • 해당 API는 어디로 요청하나요?
  • Parameter / Method / Request Body 등 확인해 주세요!
  • 제대로 요청한 것 같은데 에러가 발생해요!
  • 해당 API Response의 정확한 타입 좀 알려주세요!

이를 해결하기 위해 사내에서 제공하는 Wiki로 API 문서를 관리하게 되었습니다. 하지만 자주 변경되는 스펙일 경우 문서 최신화가 필요하지만 갱신이 잘 이루어지지 않는 단점이 있습니다. 그래서 HomeBuilder 팀은 문제를 해결하기 위해 OpenAPI Specification과 OpenAPI Generator를 도입하였으며 지금부터 자세하게 설명하도록 하겠습니다.

Episode.1

OpenAPI Specification

프로그래밍 언어에 종속되지 않게 HTTP API를 위한 표준 인터페이스를 정의한 것으로 예전에는 Swagger Specification으로 불러졌으며 Swagger에서 만들었습니다. JSON 또는 YAML로 정의가 가능하고 아래의 메타 정보들도 명세로 명시할 수 있습니다.

  • API 경로
  • HTTP 메서드
  • Request ( 매개변수, 헤더 )
  • Response Body
  • Request / Response 예제 데이터
  • Description ( 주석 )



EPISODE. 2

OpenAPI Generator

OpenAPI Generator는 OpenAPI Specification으로 작성된 문서를 변환하는 라이브러리이며 아래의 기능을 대표적으로 제공하고 있습니다.

Client

  • API 통신 함수 자동 생성
  • API 요청 / 응답에 사용되는 데이터의 타입 스크립트 타입 자동 생성
  • 예시 결과를 리턴하는 stub 서버 코드 자동 생성

Server

  • 전체적인 Server 뼈대 및 비즈니스 로직 자동 생성
  • API 기반 Service Class 뼈대 자동 생성



Episode. 3

OpenAPI Generator 활용해 보기

1. Generator Setting

OpenAPI Generator는 다양한 방법으로 사용법을 제공하고 있습니다.

  • Home-brew / NPM / Docker / CLI

저희는 프로젝트 패키지로 관리하기 때문에 NPM 형태로 설치하였습니다. NPM으로 설치할 경우 OpenAPI Generator는 JVM 기반으로 동작하기 때문에 사전에 JDK 설치가 필요합니다.

npm install @openapitools/openapi-generator-cli

2. Generator Config 파일 작성

Root 경로에 openapitools.json 파일을 생성한 후 아래의 설정 코드를 작성합니다. 저희는 타입 스크립트와 Axios 모듈을 사용하기 때문에 typescript-axios 변환 방법을 선택하였고 더 많은 방법은 해당 링크를 참조하시기 바랍니다.

{
  "$schema": "node_modules/@openapitools/openapi-generator-cli/config.schema.json",
  "spaces": 2,
  "generator-cli": {
    "version": "5.4.0",
    "generators": {
      "v3.0": {
		/* 변환 방법 결정 */
        "generatorName": "typescript-axios",
		/* 변환 결과물 경로 */
        "output": "./output/",
		/* OpenAPI Specification 문서가 정의되어 있는 경로 */
        "glob": "api-docs/api.yaml"
      }
    }
  }
}

3. OpenAPI Specification 문서 작성

Swagger에서 제공하는 공식 문서를 활용해서 API 문서를 작성합니다. Swagger Editor를 사용하면 브라우저에서 손쉽게 OpenAPI Specification를 작성할 수 있으며 예시 파일도 제공합니다.

openapi: 3.0.0
servers:
  - url: "http://localhost:8080/"
info:
  description: Test API
  version: 1.0.0
  title: OpenAPI HomeBuilder
  license:
    name: Apache-2.0
    url: "https://www.apache.org/licenses/LICENSE-2.0.html"
tags:
  - name: product
    description: Product CRUD
skip......

4. Script 등록 및 Generator 실행

해당 스크립트를 추가한 후 실행하게 되면 앞에서 설정한 Output 경로에 변환된 결과물이 생성됩니다.

/* package.json */
{
  "scripts": {
    "oas-generate": "openapi-generator-cli generate",
  },
}

/* script 실행 */
npm run oas-generate

5. Generator 결과물 분석

OpenAPI Generator가 변환을 진행하게 되면 다양한 파일들이 생성됩니다.

생성된 파일 구조

  • index.ts: 모듈을 모아주는 파일
  • configuration.ts: Axios 모듈을 사용하기 위한 설정
  • base.ts / common.ts: 공통적으로 사용하는 모듈 정의
  • api.ts: API 문서로 정의한 API 모듈을 정의 ( 직접 사용하는 모듈 )

api.ts 파일은 API 문서로 작성한 내용을 바탕으로 Request Type 및 해당 API와 통신할 수 있는 모듈을 제공합니다.

/* Request Type */
export interface Product {
    'id'?: number;
    'name': string;
    'price': number;
}

/* API 통신 모듈 */
export class ProductApi extends BaseAPI {
    public addProduct(product: Product, options?: AxiosRequestConfig) {
        return ProductApiFp(this.configuration).addProduct(product, options).then((request) => request(this.axios, this.basePath));
    }
}

episode. 4

Samanda 프로젝트 도입

서버 Package에서 Swagger를 통해 API 문서를 관리하고 있기 때문에 서버에서 OpenAPI Specification을 관리하고 Generator를 실행합니다. Generating이 완료되면 서버와 통신할 수 있는 Axios module이 생성됩니다. Client는 생성된 모듈( Axios / Type )을 import 하여 서버와 통신합니다.

Work Flow

OpenAPI Generator 자동화를 위해 Husky와 GitHub Action을 활용해 Work Flow를 설계하였습니다.

Step 1

  • 서버 개발자가 API 문서를 작성한 후 PR을 올립니다.
  • 이때 API 문서에 변경사항이 있으면 OpenAPI Generator가 지원하는 Auto Validation 기능을 사용해 문서가 올바르게 작성되었는지 확인합니다.
  • 해당 기능은 Git Hook을 손쉽게 사용할 수 있도록 도와주는 Husky 라이브러리를 사용했으며 문서 수정 후 커밋을 작성할 때 Auto Validation 기능이 동작합니다.

Step 2

  • 해당 PR에 대해 모든 개발자( FE + BE )가 코드 리뷰를 진행하고 Approve가 되면 해당 프로젝트에 Merge가 이루어집니다.

Step 3

  • Merge가 이루어지게 되면 GitHub Action을 사용하여 Auto Generating이 일어나게 되고 서버 개발자가 수정한 API 문서를 바탕으로 API 모듈이 자동 생성 및 업데이트됩니다.



episode. 5

OpenAPI Generator의 장점과 단점

OpenAPI Generator를 도입하면서 저희 팀은 아래와 같이 장점과 단점을 정의할 수 있었습니다.

장점

  • OpenAPI Specification 기반의 문서만 잘 정의되어 있다면 따로 타입을 정의하거나 API 호출 코드를 작성하지 않아도 됩니다. ( 생산성 증가 / 휴먼에러 감소 )
  • 비즈니스 로직 또는 View 로직의 구현 시간이 증가합니다.

단점

  • API 개수가 증가하게 되면 API 문서로 작성해야 하는 시간이 많이 소요됩니다.
  • OpenAPI Specification 작성법에 익숙한 사람이 적은 편입니다.
  • 코딩 스타일 / 컨벤션 / 패턴 / 모듈화 방식 / 폴더 구조 등 OpenAPI Generator가 정의한 모델로 생성되기 때문에 제한적입니다.
  • 생태계가 빈약하고 정보가 많이 부족합니다.



마무리

저희 HomeBuilder 팀은 새로운 Samanda 프로젝트를 진행하면서 아직 초기 설계 / 구현 단계에 있다 보니 FE 개발자와 BE 개발자가 협업하는 시간이 적어 OpenAPI Generator의 도입 효과를 많이 경험하지 못했습니다.

하지만 이런 작은 변화와 도전을 통해 더 나은 소프트웨어를 만드는 데 기여할 수 있다고 생각하며 이것을 통해 Samanda 프로젝트를 성공적으로 마무리할 수 있었으면 좋겠습니다. 긴 글 읽어주셔서 감사합니다:)

장우영 | HomeBuilder
장우영 | HomeBuilder

HomeBuilder 팀에서 개발을 담당하고 있는 주니어 개발자입니다.

,
👋🏻 We’re Hiring! Join Our Team NOW →