API 관련 코드 자동화

@eonlic님의 API 관련 코드 자동화에 대한 트윗 타래를 보고 우리 회사에서 어떻게 자동화 하고 있는지와 그에 관한 생각을 적어보려고 한다.

트윗 타래를 거칠게 요약하면 (이 요약 외에도 여러 내용이 많다)

1. 높은 생산성을 위해 개발팀의 현재의 자동화 수준과 미래 의지가 중요하다.
2. 자동화 수준을 테스트하려면 “API 명세가 어떻게 되어 있는지” 확인하면 된다.
3. 이상적인 경우는 서버 코드 자체가 명세가 되는 것이다. (코드로부터 자동 생성)

전반적으로 동의하는데 3번에 관해서는 약간 의견이 다르다. 회사의 기존 프로젝트는 Springfox를 사용해서 서버 코드로부터 API 명세를 만들었다. API 명세를 직접 작성하지 않고 서버 코드만 수정하면 된다는 것이 편리했다. 하지만 이때 사용하는 도구의 문제로 API 명세가 원하는 형태로 안 나오는 문제가 생겼다. 이런 경우에는 그 도구를 수정하고 관리해야 하는 불편함이 생긴다. API 명세를 직접 작성하는 수고를 줄여주지만 만능은 아니라는 것이다.

API 명세를 먼저 작성했을 때 백엔드 개발자와 프론트엔드 개발자의 소통이 원활해지는 것을 경험했다. API 명세를 먼저 작성하는 프로젝트가 더 만족도가 높았다. 개발 초기에 명세를 작성하고 검토하는 과정 중에 프론트엔드 개발자가 명세 작성에 더 개입할 수 있고 문제점을 일찍 파악할 수 있다. 문제가 늦게 파악되면 늦게 파악될 수록 기존에 개발했던 것을 고치기가 힘들다. API 명세의 초안을 검토하면서 찾아내는 것이 가장 좋고, API 명세로부터 만들어진 API client 코드를 사용하는 과정에서 문제를 발견하더라도 나쁘지 않다. 백엔드 개발이 다 끝난 뒤에 명세를 변경해야한다면 백엔드 개발자가 힘들고, 만약 백엔드에서 변경을 못 한다면 프론트엔드에서 비효율적으로 해결해야 하는 경우도 생긴다.

작성된 API 명세를 공유하고 소통하는 방식도 중요하다. 동료 한 분이 여러 문서화 도구를 비교한 뒤 Redoc이 가장 좋다고 공유해주셔서 개발팀 전반적으로 사용하기 시작했다. 초창기에는 명세 yaml 파일을 공유하고 각자 redoc을 돌려서 확인하였지만, 인턴 프로젝트로 간단한 API portal을 만들어진 뒤에는 웹에서 확인하고 있다. API Portal에서는 GitHub repository와 그 안의 명세 파일 경로를 입력하면 바로 API 문서를 볼 수 있다. 불필요한 파일 전송은 없어졌고 브랜치와 커밋을 지정하여 볼 수 있어 편리해졌다. API 명세에서 고쳐야할 부분이 있으면 GitHub에서 이슈를 만들거나 PR을 보내는 방식으로 정착하였다.

웹 프론트엔드에서 API 명세를 사용할 때에도 도구의 안정성에 유의해야 한다. 우리 팀은 OpenAPI Generator를 사용해서 API Clients를 생성해서 사용한다. 출력 형식으로는 typescript-fetch를 사용하는데 타입 정의가 자동으로 만들어져서 편리하고 안전하게 사용할 수 있다. 하지만 생성된 코드에 몇몇 문제가 있어서 직접 해결해야 했다. 기존 프로젝트에서는 OpenAPI generator를 fork해서 수정 버전을 사용하고, 최근 프로젝트에서는 생성된 코드의 몇몇 부분을 올바른 코드로 치환하는 스크립트를 사용한다. 버전이 올라가면서 문제도 해결되고 코드 구조도 나아졌지만, 아직도 남아있는 문제들이 있다.

결론적으로 API 관련 코드 자동화의 장점이 크고 여러 좋은 도구들이 있지만, 노력 없이 쉽게 되지는 않는다는 얘기를 하고 싶었다. 수고스럽더라도 API 명세를 직접 작성하는 것이 개발 과정을 더 원할하게 할 수도 있다. 또 API 명세를 여러 개발자가 공유하고 수정하고 코드 생성하는데에도 지속적인 노력이 필요하다. 마지막으로 OpenAPI 생태계와 API 관련 코드 자동화를 적극적으로 도입한 동료 개발자들에게 감사하다는 말을 전하고 싶다.

웹 프론트엔드, 음악, 책 등등
by 조용준