명세서를 현명하게 바꾸려면

저희 그래도… 친하죠?

문제 상황

웹소켓의 이벤트 명세를 바꾸게 되었는데, 프론트 - 백 간의 연동 과정에서 엄청난 실수를 저지르고 말았습니다. 바로 반환되는 데이터를 바꿔버린 것입니다.

반환되는 데이터만 바뀌면, 그냥 알려주면 되는 것 아닌가? 라는 생각이 드실 수 있습니다. 그런데 문제는, 반환되는 데이터의 기준 을 바꿔버렸던 것입니다.

API를 정의할때 입력 과 출력 값만 나오면 된다곤 하지만, 결국엔 어떤 값을 넣으면 서버에 저장되는 데이터가 어떻게 바뀌는지에 대해서는 명세가 안되었던 것 입니다.

“바뀐 명세를 확인해주세요!” 라고 말하고 너무 프론트 분에게 맡겼던 것이 큰 실책이었던 것입니다. 바뀐 명세가 제대로 작동되지 않거나, 충분히 설명되지 않았습니다. 글을 쓰는 것이 많이 어려웠는데, 계속된 문서화랑 코딩으로 인해 체력이 바닥이 나서 제대로 글을 못쓴 것도 원인 같습니다. 이런 상황에서도 문서를 잘 쓸 수 있어야 개발자일까.. 고민하게 됐습니다.

해결 과정

프론트엔드 캠퍼분께서 계속해서 질문을 주셨습니다. 덕분에 계속 개선을 할 수 있었습니다. 하지만, 그럼에도 해결이 되지 않았고 결국 페어프로그래밍 을 했습니다.

같이 프로그래밍을 하면서 데이터가 만나는 지점인 엔드포인트(컨트롤러, api 호출함수)가 아니라, 실제로 프론트 부터 백까지의 비즈니스 로직의 전체 흐름을 제가 보고 나니 어떻게 하고싶었던 것인지 다시 정의를 할 수 있었고, API를 보여줄 때는 서버의 전체 흐름도 알려주어야겠다 라고 생각하게 되었습니다.

바뀐 명세서, 훨씬 명세서 다워졌다.

이전 명세서, 타입에만 신경쓰다보니 무슨 이벤트인지 모르겠다..

이렇게 서버에서 일어나는 동작 자체를 명세하도록 바꾸었고, 스터디 기능을 “구현 및 연동” 속도가 스터디 세션 “연동” 속도보다 3배 빨라졌습니다. 스터디 세션 기능의 경우 3일 걸렸고, 스터디 기능 구현 및 연동은 1일만에 완료했다.

스터디 기능 구현 과정에서 스터디 세션 기능이 구현이 되어있었다는 점을 감안해도, 스터디 기능은 구현 및 연동 과정이 하루만에 끝났고, 스터디 세션의 경우 백엔드 구현 후 이미 완료한 프론트 엔드 작업과 연동 과정에만 3일(이번주 월 ~ 수)이 걸렸음을 생각하면 거진 3배 빨라졌습니다.

명세서를 현명하게 바꾸려면..?

명세서를 현명하게 바꾸기 위해서는 문서화 와 실제 구현 의 순서를 반드시 바꿔야함을 깨달았습니다.

여기서 문서화란 단순히 문서 작성을 하는 것이 아니라, 문서를 읽는 사용자들에게 확인받기 까지 완료하는것이 문서화 입니다.

문서화에서 커밋하기 전 상태를 나타내기

문서화에서 확실하지 않은 경우 일단은 문서를 수정하지 말지 고민되는 경우가 많았습니다. 그래서 수기로 작성하는 경우, 명세서에 마이너 버전을 두는 것도 좋다고 생각했고, 변경 기록을 또 남기기 위해 차라리 수기로 작성할 때는 다음에는 깃허브 레포를 이용해볼까 합니다.

실제 데이터를 기반으로 문서화 하자.

그리고 가장 중요한건 실제 구현 과 문서 와 일치를 최대한 시킬 수 있도록 해야합니다. 여기서 제안하는 것이 Swagger 입니다. 실제 구현에 필요한 DTO를 정의를 해두고, API 가 응답하는 DTO를 일정하게 만들어 API 응답의 일관성을 지키면서, Swagger 로도 문서화를 시켜서 자동으로 생성할 수 있도록 만드려고 합니다.

웹소켓의 경우 Swagger로 문서화할 수 없지 않나요?

네 그렇습니다. 그렇지만, 코드 단위에서 반환 객체를 모킹하여 문서화를 할 수 있다고 생각합니다. 코드를 돌려보진 못하지만 적어도 특정 실제 객체에 따라 출력값에 실제 이 객체를 사용한다는 점입니다.