OpenApi Specification Generator 도입

도입 배경

2023년 6월에 휴톰에 프론트엔드에 합류하며 annotation-tool을 h-vat으로 리뉴얼하는 작업을 맡게되었다.

백엔드 개발이 먼저 진행되다가 프론트(본인)이 투입되었는데, 우선순위에 따라 타 프로젝트로 리소스 투입이 되면서 백엔드 개발이 중단되는 상황이 되었었다.

타 프로젝트로 투입되기 이전에는 백엔드 개발자도 있으니 아래의 순서대로 개발을 시작할 예정이었다.

h-vat에는 레거시를 개편하는 프로젝트이므로 기획자가 존재하지않다. 프론트엔드가 UI 개발만을 하는것이 아니라 백엔드와 연결되어있는 개발 영역이 있는 경우에, 프론트엔드와 백엔드 개발자가 API 스펙을 사전에 협의해야한다.

API설계는 어떻게 할까?

요구사항을 분석하고 API 스펙을 협의한다
- 백엔드 개발자 : 협의된 API 스펙에 맞게 API를 개발한다.
- 프론트엔드 개발자 : 협의된 API를 모킹한다.
백엔드 개발자의 API개발이 완료된다.
- 프론트엔드 개발자 : 모킹되어있는 API를 완성된 API로 교체한다
반복… 후 완료

하지만 위에서 말했듯 백엔드 개발 인력이 사라지면서 프론트엔드가 붕 떠버린 상황이 약 3주간 지속되었다.

답답한 마음에 백엔드 개발까지 맡기로 하였고 본인이 데이터베이스 재설계, 백엔드 재설계 및 개편, 프론트엔드 재설계 및 개편을 하게되었다. 이왕 혼자 모든걸 프로젝트를 맡게되며 프론트엔드 개발을 진행하며 가장 불만이었던 서버 요청/응답 관련 타입을 직접 작성하고, 변경되면 직접 다시 변경해야하는 점이 생각났다.

그렇다면 데이터베이스 ↔ 웹 애플리케이션 서버 ↔ 웹 클라이언트 모두 같은 타입을 사용하여 타입안정성이 있는 개발과 동시에 얼마나 꿀빨기(?)가 가능한지 궁금해졌다.

이를 실현시켜줄 도구를 찾아보고있던 도중 OpenApi Specification Generator를 알게되었다

OpenApi Specification란 무엇인가

보통 openAPI 또는 OpenAPI Specification(OAS)라고 부르는데, 이는 Restful API를 정의된 규칙에 맞게 API 스펙을 json or yaml 파일로 표현하는 방식을 의미한다.

정리하자면 RESTful API 디자인에 대한 정의 표준이라고 생각하면 될것이다.

Swagger는 2010년에 개발하기 시작되었고 한회사의 API용 UI 솔루션용으로 개바되었고, SmartBear라는 회사에서 Swagger를 인수했다. 그리고 SmartBear는 2015년 OpenAPI Initiative에 Swagger를 기부하며 OpenAPI Specification라는 이름으로 변경되었다

OpeanAPI : 이전에 Swagger Specification으로 알려진 Specification 자체(RESTful API 디자인에 대한정의)
Swagger : OpenAPI를 Implement하기 위한 도구

H-vat에는 어떻게 도입했는가?

반복되는 작업이 싫었던 나에게 필요했던것은 아래의 두가지였다.

api 인터페이스를 담고있는 클래스
api 리턴 타입 인터페이스 객체

이 두가지가 API 스펙 파일을 전달받고 스크립트를 돌리면 자동으로 생성되도록 자동화하는 과정이 필요했다.

openapi specification generator 가 그 과정을 실현화 해줄것이다.

mustache 템플릿 기반 코드 자동 생성

Frontend

API 통신 함수 자동 생성
API 요청/응답에 사용되는 DTO 타입(typescript) 정의 자동 생성
예시 결과를 리턴하는 stub 서버 코드 자동 생성
서버 개발이 끝나지않더라도 개발 가능

프론트엔드의 이점이 잘 와닿지 않을 수 있기에 풀어 설명하자면

code generated

위의 스크린샷은 자동으로 생성된 AuthsApi 인터페이스를 담고있는 클래스다. 이것을 보면 fetch/axios 호출을 직접 짜지 않아도 된다. 더이상 프론트엔드 개발자가 API 문서를 보고 신경을 써야할것이 효과적으로 줄어든게 된다.

HTTP Method를 보고 어떤 Method를 써야하는지?
api end point가 맞는지?
request header에 어떤것이 들어가야하는지?
resposne type은 어떤 타입인지?
exception은 어떠한지

사람이 짜는 코드의 양이 줄어드는게 무엇이 좋아지는가?

비지니스 로직 or 화면에 집중하는 시간이 증가한다.
휴면 에러가 감소한다
- api end point 오탈자 방지
- 타입정의 오류

Backend

서버 개발자들에게는 도대체 무슨 이점이 있을까를 한번 고려해보자

프론트엔드 개발자들과 동일한 도메인에 대해서 말하지만 코드베이스에서 다른 이름으로 불리는것을 방지할 수 있다

위의 코드는 openapi-specification-generator 적용 전의 코드이며, 차례대로 h-vat의 프론트엔드와 백엔드의 동일한 개념인 유저가 로그인을 수행하는 메서드다.

서버와 클라이언트의 메서드명의 Align이 맞춰졌다. 그리고 여기서 기대되는 효과가 하나있다. 서버에서 방치되던 api를 삭제할시 클라이언트측에서도 해당 api가 삭제되므로 타입스크립트의 컴파일러가 이를 잡아 프론트엔드 개발자는 사라진 api를 항상 추적할수 있게된다.

nestjs-openapi-tools

@nestjs/swagger 의 어노테이션의 도움을 받아 위의 swagger-ui 문서를 만들어내면 된다.

이런식으로, OpenAPI Specification을 json또는 yaml 문서로 기술하면된다. 본인의 경우 아래의 라이브러리를 통해 nest-swagger의 어노테이션을 이용하여 openapi.json파일로 자동 생성시켜주었다.

타 프로젝트에는 어떻게 도입 및 설득할것인가

openapi specification은 사람과 컴퓨터가 쉽게 API를 이해하고 언어에 구애받지 않고 문제를 해결하는것을 목표로한다.

개발자가 문서 작성하는데 시간을 할애하는 것은 꽤 지루한 일임에 공감한다. 하지만 상세한 문서가 있다면 최종 사용자인 프론트엔드 개발자와 타 백엔드개발자뿐만 아니라 비지니스 이해 관계자에게도 도움이 된다는것은 명백한 사실이다.

그렇다면 문서를 설계하기위해 어떤 노력을 해야할까? 그리고 어려워진 문서 관리 방법에서 다가오는 개발자의 불편함은 무엇인지 알아봐야한다.

먼저 프론트엔드 개발자가 API 문서로부터 고통받는 순간들이 무엇이 있을까?

백엔드 개발자에게 전달받은 API 명세가 적혀 있는대로 동작하지 않아 당황스러웠던 적이 있다
개발일정에 쫒겨 API 문서를 언제쯤 받을 수 있을까 백엔드 개발자를 닥달해본 적이있다

반대로 백엔드 개발자가 API 문서로부터 고통받는 순간들은 무엇이 있을까?

처음 API 설계를 하기 위해서 빈 페이지를 열고 어떻게 설계할지 생각하다 한숨을 쉬게된다
API 코드 수정 이후 매번 변경된 API 명세를 API 문서에 반영해야한다.
더이상 사용되지않는 API가 API 문서에 방치되지않도록 신경을 써야한다

Code First vs Api First

API 설계는 애플리케이션의 여러 요소가 통신하는 방식을 결정하므로 중요하다. 개발자는 API를 구현할때 code first 혹은 api first 두 방법 중 하나를 선택한다.

두방법 모두 장단점이 존재한다.

Code First

코드를 먼저 작성한 다음 사후에 문서를 작성하는 방식이다. 개발자는 일반적으로 이 접근 방식을 사용하여 코드를 작성한 후 도구를 사용하여 코드에서 API 문서를 생성한다.

해당 방식은 API 설계 요구 사항을 명확하게 이해하고있는 개발자에게 적합할수 있다. 문서화 전에 코드를 작성하면 빠르게 개발하고 출시가 가능하다. 개발기간이 빨라야하는 소규모 팀 혹은 반복적인 개발이 많은 프로젝트에 적합한 접근 방식일 수 있다.

하지만 이 방식은 테스터나 기술 문서 작성자와 같은 다른 이해관계자가 API를 이해하기가 어렵다. 이들은 자동화된 테스트를 작성하거나 문서를 작성하기 위해 정확한 API 정의를 참조하는 API 코드베이스를 파헤치고 API 도구를 사용하여 작동방식을 이해해야한다는 단점이 존재한다.

Api First

코드를 작성하기 전에 상세한 API 정의를 작성하는 방식이다. 시간이 오래걸린다는 단점이 존재하지만 여러 프로그래밍 스펙에 맞게 코드를 생성하고 구현 전반의 일관성을 짧은 시간 내에 개선할 수 있다.

Api 우선 방식을 사용하여 얻을 수 있는 장점은 아래와같다.

프론트엔드 개발자와 백엔드 개발자 그리고 비지니스 이해관계자가 동일한 정보를 공유할 수 있다는 점이다.

개발팀이 동시에 작업이 가능하다. 조직내의 여러팀이 서비스의 API 스펙에 대해 정의하면 해당 팀들이 동시에 여러 API 작업이 가능하다. 프론트엔드 개발자는 다음 API 개발로 넘어가기 이전에 API에 대한 업데이트가 릴리즈 될때까지 기다릴 필요가없다. 우선 정의된 API 스펙을 기반으로 개발이 가능하다.

API와 코드는 다양한 프로젝트에서 재 사용이 될 수 있다. 개발팀이 새로운 앱을 구축하고자 할때 동일한코드를 작성하는 시간은 만만치않게 큰 비용이다.

API를 정의한 파일을 가져올 수 있는 도구를 사용한다면 대부분의 과정을 자동화할 수 있다. Swagger Hub를 사용하여 API 정의 파일을 가져올 수 있으며, 이 파일을 API 도구와 함께 사용하여 API 생성 자동화가 가능하고 생산속도를 크게 높일 수 있다.

종합

위의 내용을 종합해보면 아래의 사진과 같은 방법으로 반복적인 설계를 하고 도구를 통해 개발기간 단축과 문서 관리의 관리포인트 절감이 핵심인것으로 파악된다.

다행히 현재 휴톰 플랫폼팀의 API 개발 워크플로우는 api first를 사용하고있었고, 백엔드 개발자 동료분들도 openapi specification을 통해 swaggerUI를 만들어 프론트엔드 개발자들과 소통을 하고있었다.

우리의 api 디자인 방법에서 변경되어야할것은 google docs에서 논의되던 API Spec의 개발자간의 규약을 openAPI specification로 옮겨가는것이다.

그리고 추가로 바라는 것은 문서의 단일화다. 본인은 동료들을 믿지만 위에서 말했듯 휴먼에러는 언제나 발생할 수 있고, 인적자원은 항상 불안적 존재임에는 틀림없다. 이를 제도 혹은 도구로 강제하여 방지할 수 있고 개발 및 스펙문서 작성 시간 단축까지 이어진다면 좋을 경험이 될것이다.

참고자료

Code-First vs. Design-First: Eliminate Friction with API Exploration

Understanding the API-First Approach to Building Products