Skip to Content
BackendOpenAPI 명세와 Redocly 문서 빌드를 CI에 연결하기
💻 Backend2023년 10월 18일

OpenAPI 명세와 Redocly 문서 빌드를 CI에 연결하기

#e-commerce#payment-expansion#backend#api-docs
Payment Expansion · Series 3 · Rebuild & Quality8 / 14Backend
API 명세와 스키마를 함께 관리하고 문서 빌드를 자동화한 과정입니다.
← 이전 글: DynamoDB 속성 이름 불일치와 KMS 설정 확인다음 글: 카카오페이 v2 테스트 커버리지 80% 맞추기 →

카카오페이 v2를 새로 만들면서 API 문서 관리 방식도 바꿨습니다. 기존에는 API Blueprint로 작성한 .apib 문서를 사용했는데, 요청·응답 모델과 검증용 스키마, 문서를 함께 관리하기가 불편했습니다.

그래서 OpenAPI 명세를 저장소에 두고, 같은 스키마를 재사용하며 Redocly로 문서를 만드는 구조를 제안했습니다. 구현 전에 프론트엔드와 QA, 글로벌 결제 팀이 같은 명세를 보고 개발할 수 있도록 하는 것이 목적이었습니다.

API Blueprint에서 OpenAPI로 전환

API Blueprint는 Markdown과 비슷한 형태로 리소스와 요청·응답 예시를 작성할 수 있습니다. 문서를 빠르게 쓰기에는 편했지만, 우리가 필요했던 것은 문서를 읽는 것 외에 스키마를 여러 곳에서 재사용하는 구조였습니다.

OpenAPI로 옮기면서 요청 파라미터와 응답 구조를 스키마로 정의하고 참조할 수 있도록 정리했습니다. 구현 코드에 문서용 annotation을 많이 추가하기보다, 별도 명세 파일에서 모델과 문서 기준을 관리하는 쪽을 선택했습니다.

Redocly는 그 OpenAPI 명세를 검증하고 HTML 문서로 만드는 도구였습니다. OpenAPI가 명세 형식이고 Redocly는 이를 다루는 도구라는 점을 구분해서 보면 역할이 명확합니다.

검증과 문서에 같은 스키마 사용

당시 요청·응답 스키마는 공통 라이브러리와 함께 서비스에서 재사용하고 있었습니다. 문서를 위해 같은 필드를 다시 작성하기보다, OpenAPI에서도 그 스키마를 참조하도록 구성했습니다. 공통 라이브러리 구조는 카카오페이 v2 구축 글에서 다룹니다.

아래는 같은 개념을 보여주는 간단한 OpenAPI 예시입니다. 내부 API를 옮긴 것은 아닙니다.

yaml
sample/openapi.yaml
openapi: 3.0.3
info:
  title: Example Payment API
  version: 1.0.0
paths:
  /registrations:
    post:
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegistrationRequest'
      responses:
        '202':
          description: Registration request accepted
components:
  schemas:
    RegistrationRequest:
      type: object
      required: [provider]
      properties:
        provider:
          type: string

이렇게 명세를 한곳에서 관리해도 구현이 자동으로 맞춰지는 것은 아닙니다. 명세를 대상으로 하는 lint와 실제 API 응답을 검증하는 테스트는 역할이 다릅니다. 스키마를 재사용하는 구조와 구현 검증을 함께 유지해야 했습니다.

CI의 명세 검증과 문서 빌드

Redocly 빌드를 프로젝트 빌드 과정에 연결했습니다. 로컬에서 문서를 만드는 명령과 CI에서 실행하는 명령을 맞추고, 명세 검증과 HTML 생성, 생성한 문서의 배포를 이어서 실행하도록 구성했습니다.

CLI가 설치된 환경에서는 다음처럼 명세 lint 와 HTML 빌드 를 실행할 수 있습니다.

bash
sample/build-api-docs.sh
redocly lint openapi.yaml
redocly build-docs openapi.yaml --output docs/payment.html

실제 파이프라인에서는 오류가 나면 다음 단계로 넘어가지 않도록 종료 상태도 처리해야 합니다. 명세 문법이 맞는지만 보는 lint로 구현과 문서의 모든 차이를 잡을 수 있는 것은 아닙니다.

Docker 실행 결과의 전달

CI에 연결하는 과정에서는 문서 빌드가 실패했는데 상위 작업에는 성공으로 보이는 문제도 다뤘습니다. 컨테이너 안의 명령이 실패해도 실행 스크립트가 그 종료 코드를 전달하지 않으면 이런 상황이 생길 수 있습니다.

이 경우 Docker 자체의 문제라고 보기보다, CLI부터 래퍼 스크립트와 빌드 태스크까지 실패가 전달되는지 확인해야 합니다. 문서 파일이 만들어졌는지와 빌드 상태가 성공인지도 함께 봐야 했습니다.

명세를 기준으로 한 팀 협업

생성한 문서는 내부 개발자 센터에 반영되도록 연결했습니다. 프론트엔드와 다른 팀은 그 명세를 보고 개발을 이어갈 수 있었습니다. 구현과 별개로 문서를 전달하고 다시 수정하는 일을 줄일 수 있었습니다.

다른 팀도 API Blueprint를 사용하며 비슷한 불편을 겪고 있었습니다. Confluence에 정리한 설계 문서를 보고 연락해 온 경우도 있었습니다. 이후 이 구조가 다른 결제 서비스에도 공유됐습니다.

다음 글에서는 테스트 커버리지 80% 기준을 맞춘 과정을 다룹니다.

Last updated on