OpenAPI Specification와 Code Generator를 사용한 API 명세서 관리 간편화

[Mingyum-Kim]

PR의 목적이 무엇인가요?

현재 개발 문서화 과정의 문제

노션과 스웨거를 동시에 사용하고 있는 지금 아래 두 가지 문제가 있다고 생각했습니다.

• 중복 작성이 필요하다.
• 스펙 변경 시 스웨거만 변경되어 혼란이 생긴다.

하지만 스웨거로 일원화 하기에도 해결되지 못하는 불편함이 있었어요.

• 상세한 스펙 작성의 불편함
• 코드 리뷰를 통해 개발 서버에 머지 되어야 명세를 제공할 수 있다는 불편함. 즉 반영에 시간이 걸림.

두 가지 불편함을 이렇게 개선했어요.

• 상세한 스펙 작성의 불편함 👉 JSON 방식으로 스펙을 작성하여 어노테이션을 일일이 적는 것보다 시간을 절약할 수 있다.
• 반영에 시간이 걸림 👉 JSON 파일만 개발 서버에 쇽하고 올리면 자동으로 명세가 만들어져 프론트엔드 개발자들이 빠르게 바뀐 명세를 확인할 수 있다.

JSON에 스펙을 작성하고 Gradle Build를 하면, 자동으로 스웨거 인터페이스와 DTO가 만들어지도록 했어요. 명세가 바뀌더라도 중복으로 문서를 수정할 필요는 없습니다!

이슈 ID는 무엇인가요?

• 스웨거를 사용한 API 명세서로 일원화하기 위해 기존 문제 해결 #509

설명

일단 우리 프로젝트에 적용하는 것을 우선으로 두고 구현하였어요.
세세하게 수정할 부분이 있는데, 차차 관리하는 것으로 하고 일단 논의 차 PR 먼저 올립니다. 😉

이 PR이 적용되고 난 후 기대하는 API 개발 시나리오는 다음과 같아요.

API 개발 시나리오

• contract.json에 json형식으로 API 명세를 작성한다.
• 변경된 contract.json 파일을 API 명세 전용 브랜치 (리뷰 필요 없음) 에 올린다.
• 개발 서버에 API 명세 전용 도커 컨테이너에 변경된 API 스펙이 적용된다.
• 이후에 프로덕션 개발을 시작한다.
  • ./gradlew build를 입력해 자동으로 스웨거 인터페이스와 DTO를 생성한다.
  • 생성된 인터페이스와 DTO를 활용하여 프로덕션 개발을 진행한다

개발 서버에 API 명세가 적용되는 시나리오

• 수정된 JSON 파일이 개발 서버에 업로드 된다.
• 해당 JSON을 볼륨에 마운트하고 있는 도커 컨테이너를 재가동한다.
• dev.mouda.site의 특정 포트에 접근하면 변경된 스웨거 UI가 호출된다.

도커 컨테이너 테스트는 로컬에서 이미 진행되어서, 승인 되면 등교 후 빠르게 작업해놓겠습니다 👱‍♀️

자세한 내용은 내일 쯤 팀 블로그에 기재해놓을게요.

질문 혹은 공유 사항 (Optional)

Code Generator가 인터페이스와 DTO를 자동으로 생성하는 부분에서 아쉬운 점이 있다면,

• 현재는 인터페이스와 DTO 클래스 위치가 도메인 별로 분리되어있는데, 이 방식을 사용하면 하나의 패키지에 몰아넣게 될 것 같아요.
• @LoginMember는 명세에 포함되지 않지만 컨트롤러 파라미터에는 포함돼요. 미스매치가 생겨서 지금 당장 인터페이스를 활용할 수 없을거에요.

그래서 당장 적용하긴 어려울 것 같고, 이 방식에 대한 피드백을 받고자 PR 올려요. 참고해주세요!