Increase는 API 정의를 코드에 두고 이를 OpenAPI 스키마로 변환해 문서와 언어별 SDK 등을 만든다. 회사 측은 이 방식으로 구현과 문서의 불일치를 막고, 수백 개 엔드포인트로 확장된 API의 개발자 경험을 한 명의 엔지니어가 담당할 수 있었다고 설명한다.
Increase의 내부 프레임워크에서는 각 API 메서드가 HTTP 동사와 경로, 매개변수 및 응답 형태를 정의한다. 프레임워크는 규칙 준수를 검사하고, 가능한 경우 런타임이 아닌 빌드 시점에 오류를 찾는다. Ruby 코드의 타입 검사에는 Sorbet을 사용한다.
프레임워크는 HTTP 요청을 타입이 지정된 요청 객체로 변환하고, 리소스 ID를 데이터베이스 모델과 연결해 불러오는 기능도 제공한다. 또 잘못된 매개변수 이름을 바로잡아 제안하거나, 객체가 샌드박스 환경에 있는지 확인하고, 권한을 검사한다. 요청을 파싱하는 단계에서 발견한 여러 오류를 한 응답에 모아 반환할 수도 있다.
Increase는 Ruby 리플렉션을 이용해 코드 정의를 OpenAPI 3.1 스키마로 변환한다. 회사는 규모가 큰 스키마를 손으로 작성하면 구현과 일관성을 유지하기 어렵다고 본다. 공통 리소스 정의는 $ref로 재사용하고, 열거형 각 항목의 설명처럼 OpenAPI 표준에 아직 포함되지 않은 기능은 확장 필드로 생성한다.
생성한 스키마는 API 참조 문서와 언어별 SDK, Postman 컬렉션의 기반이 된다. 문서 사이트는 스키마 확장 기능을 활용하기 위해 직접 제작한다고 설명한다. 프레임워크 자체는 코드베이스의 ORM과 연결되는 부분이 있어 오픈소스로 공개하지 않기로 했다.
댓글 (0)
로그인하면 이 기사에 내 생각을 남길 수 있어요