원문: Malcolm Kee, OpenAPI: A backend developer's tool, a frontend developer's friend

저는 제 작업 흐름에 TypeScript가 유용하다고 생각합니다. 코드의 일관성 없는 가정을 인식해서 버그를 방지해 주기 때문에 코드에 더 확신을 가질 수 있죠.

하지만 TypeScript는 컴파일 시간에 접근할 수 있는 코드베이스 이외에는 타입 검사를 할 수 없습니다. TypeScript가 런타임에 응답이 어떻게 될지 알 방법은 없기 때문에 fetch 호출은 항상 any (또는 unknown)가 됩니다. 물론 응답 타입을 직접 선언하여 타입 검사하는 '척'을 할 수도 있겠지만 호출하는 API는 변경될 수 있기 때문에 이런 수작업은 계속될 것입니다. 그리고 우리 프로그래머는 결국 실수를 하게 되기 때문에 수작업을 싫어하죠. ~~게으르기도 하고요~~.

이런 TypeScript의 한계를 극복하기 위해 GraphQL 코드젠을 통해 GraphQL을 이용하거나 tRPC를 통해 gRPC를 이용하는 등의 방법이 있습니다. 이런 도구들은 강력하고 설정하기도 쉽지만 실제로 채택하기는 쉽지 않습니다. API 서버 기술 스택을 변경해야 하는데 우리 중에 그럴 권한이 있는 사람이 많지는 않으니까요.

하지만 여러 라이브러리를 공부하고 조합할 의향이 있다면 백엔드 기술 스택을 변경하지 않고도 이 문제를 해결할 수 있는 도구가 있습니다. 바로 OpenAPI죠.

OpenAPI란 무엇인가

OpenAPI는 API를 만들기 위해 사용한 프로그래밍 언어에 상관없이 REST API가 표현되는 방식을 표준화하기 위한 사양입니다. OpenAPI에 기반하여 생성된 문서는 OpenAPI 문서라고 부르며 JSON이나 YAML 형식으로 작성될 수 있는 JSON 객체입니다. OpenAPI는 때때로 'Swagger'¹라고도 불립니다.

OpenAPI 문서는 보통 다음의 두 가지 방식으로 만들어집니다.

서버에서 사용하는 프로그래밍 언어나 프레임워크의 코드 애노테이션을 통해 생성됩니다. 예를 들어 NestJS는 자체 라이브러리를 통해 OpenAPI 문서 생성을 지원하며 SpringFox는 Spring 프레임워크를 사용하여 만들어진 API 서버의 OpenAPI 문서를 생성합니다.
(직간접적으로 OpenAPI 편집기를 사용하여) API 개발자들이 직접 작성하여 API 스텁 코드를 생성하기 위해 사용합니다.

OpenAPI 문서의 일반적인 사용 방법

OpenAPI 문서의 가장 일반적인 사용 방법은 swagger-ui나 그와 비슷한 Redoc 같은 도구를 통해 실시간으로 확인할 수 있는 HTML 페이지를 만드는 것입니다. 이를 이용해 코드를 자세히 살펴보지 않고도 누구든 쉽게 서버의 엔드포인트를 탐색할 수 있죠. UI를 보신 적이 없다면 여기서 예시를 확인하실 수 있습니다.

사용자는 이 페이지를 통해 서버에 실제 요청을 할 수 있기 때문에 기술 지원 인력 등의 사용자가 API 요청을 호출할 수 있는 방법을 제공해야 할 때 비용을 절감할 수 있습니다. UI를 만들기 위해 추가로 기술적 노력을 쏟을 필요가 없기 때문이죠.

OpenAPI 문서는 각 엔드포인트의 예상 요청과 응답을 명확하게 표현하기 때문에 코딩 전에 개발자 간의 예상과 이해를 일치시키기 위한 설계 문서로 사용되기도 합니다. 또한 많은 팀들이 자신들의 개발 도구나 Postman과 같은 테스트 도구에 OpenAPI 문서를 더해 API 테스트에 사용하기도 합니다. OpenAPI 문서에 각 엔드포인트에 대한 설명이 충실히 작성되어 있다면 테스터와 API 개발자 간의 수동적인 커뮤니케이션이 없어도 테스터 혼자 완벽하게 API를 테스트할 수 있습니다.

덜 일반적인 OpenAPI 문서 사용법

비교적 덜 알려져 있지만 여전히 아주 유용한 OpenAPI 문서 활용 기회는 다음과 같습니다.

클라이언트 SDK 생성

SDK(소프트웨어 개발 키트, Software Development Kit)는 여러분이 사용하는 서비스가 제공하는 도구 집합입니다. 예를 들어 AWS는 개발자에게 서로 다른 프로그래밍 언어를 이용해 AWS의 기능에 편리하게 접근할 수 있도록 AWS SDK를 제공합니다. API의 SDK는 내부적으로 API를 호출하는 클래스나 패키지를 주로 지칭합니다. 이러한 SDK는 타입 검사 같은 언어의 기능을 지원하는 등 개발자 경험을 향상하기 위해 클라이언트 측의 프로그래밍 언어로 구현됩니다.

TypeScript를 포함해 OpenAPI 문서를 변환하여 서로 다른 프로그래밍 언어의 클라이언트 SDK를 생성하는 오픈소스 도구들이 많이 있습니다. 예를 들어 openapi-typescript-codegen ²을 이용해 TypeScript 인터페이스와 API 요청 함수 호출을 생성할 수 있습니다. 이를 통해 여러분의 코드 중 네트워크 요청에 관련된 부분을 올바르게 타입 검사할 수 있습니다. 이 과정을 자동화하여 호출하는 API가 OpenAPI 문서를 업데이트할 때마다 코드 생성이 다시 실행되어 자동으로 갱신되도록 할 수 있습니다. 프론트엔드 코드에서 사용 중인 필드를 제거하는 등 사용에 영향을 미치는 변경의 결과는 타입 오류로 이어집니다.

모의 서버(Mock server) 생성

모의 서버 생성은 OpenAPI 사양을 통해 이루어지는 또 다른 유형의 코드 생성입니다. SDK 생성과 유사하지만 목적이 다르죠. OpenAPI 사양을 통해 생성된 모의 서버 코드는 일반적으로 테스트에 사용됩니다. API를 호출하는 프론트엔드 애플리케이션에 대한 테스트를 실행할 때 API 동작을 시뮬레이션하는 서버로 이용하는 것입니다. 실제로 이 기능이 얼마나 유용한지는 OpenAPI 사양의 품질(예: 사양에 포함된 예제)에 따라 크게 달라지는데, 모의 서버에서 반환되는 응답은 해당 예제에 의존하기 때문입니다.

API 게이트웨이 구성

API 게이트웨이는 클라이언트와 모든 백엔드 서비스 사이에 위치하는 마이크로서비스 아키텍처의 일반적인 구성 요소입니다.

OpenAPI 문서를 사용하면 API 작업의 특정 요구 사항을 포함할 수 있으며, 이를 사용하여 API 게이트웨이를 구성할 수 있습니다. 예를 들어 API에서 연산에 대한 속도 제한을 지정할 수 있습니다. OpenAPI 문서가 변경되면 자동화 프로그램이 이를 감지하고 그에 따라 API 게이트웨이 속도 제한 규칙을 구성할 수 있습니다.

엣지 함수 생성

엣지 함수는 여러분 제품의 사용자 근처 어딘가인 '엣지'에서 동작하는 람다 함수입니다. 엣지 함수에 익숙하지 않다면 람다 함수를 위한 CDN 같은 것이라고 생각할 수 있습니다. 엣지 함수는 사용자와 더 가까운 곳에서 코드를 실행하여 더 빠른 응답을 제공해 줄 수 있도록 합니다.

인가 요구 사항과 요청 본문 스키마는 OpenAPI 문서에서 표현될 수 있으므로 기술적으로 OpenAPI 문서를 사용하여, 요청이 서버에 도달하기 전에 엣지에서 요청 페이로드를 검증하는 엣지 함수를 생성할 수 있습니다.

호환성이 보장되지 않는 변경 감지

큰 기업의 API나 외부에 공개된 API 같이 많은 클라이언트가 사용하는 API는 적절한 계획과 발표 없이 호환성이 보장되지 않는 변경이 일어나지 않도록 하는 것이 중요합니다. OpenAPI 사양은 파싱하기 쉽기 때문에 openapi-diff 패키지같은 라이브러리를 사용하여 아래와 같은 API의 변경 사항을 감지하도록 할 수 있습니다.

경로 제거
메서드 제거
요청 페이로드에 필수 필드 추가
응답 내 필드 제거

이러한 자동화를 더 쉽게 수행하려면 OpenAPI 문서를 소스 관리에 커밋하는 것이 가장 좋은 방법 중 하나입니다.

결론

REST API 서버를 유지관리하는 백엔드 개발자가 사용하는 경우 OpenAPI는 개발 및 다른 이해관계자와의 커뮤니케이션을 돕기 위해 많은 도구와 통합됩니다. 프론트엔드 개발자의 경우 OpenAPI는 수동으로 작성하고 싶지 않은 코드를 생성할 수 있게 해줍니다. OpenAPI는 GraphQL이나 gRPC만큼 멋지게 들리지는 않지만 많은 프로그래밍 언어 및 프레임워크와 잘 통합되기 때문에 REST API 또는 여러 백엔드 언어를 사용하는 회사에서 유일하게 실행 가능한 해결책이 될 수 있습니다.

OpenAPI 사양은 또 다른 사양인 SmartBear Software의 Swagger 사양에 기반하여 만들어졌기 때문에 이렇게도 불립니다. ↩
몇 가지 옵션이 있지만 심도깊이 비교하지는 않겠습니다. 저에게는 지금까지 이 라이브러리로 충분했기 때문에 이 라이브러리를 계속 사용하고 있습니다. ↩

OpenAPI: 백엔드 개발자의 도구, 프런트엔드 개발자의 친구

Table of contents