Spring REST Docs를 쓰고자 합니다.

Spring REST Docs 를 사용하고자 하는 이유에 대해 말씀드리기에 앞서, 사전에 필요한 지식과 선례를 통한 문제 인식을 살펴봅니다.

 

API 문서화 왜 하는 걸까?

 

 

 

표준화 된 API 명세서를 작성할 경우, Front-End, Back-End 개발자 간의 협업을 촉진하며,

외부 개발자가 소프트웨어를 쉽게 이해하고 활용할 수 있게 합니다.

더불어 정확하고 최신 업데이트 된 API 문서는 시스템의 에러를 빠르게 찾고 해결하는 데 도움이 됩니다

 

저희들은 이미 협업을 해본 개발자로서, API문서의 필요성과 사용하는 이유를 이미 숙지하고 있다 생각합니다. 그러나 위 설명에 적힌 API 문서 최신 업데이트는 종종 실수하는 요소입니다.

 

(실제로 현재 리펙토링 하고자 하는 기존의 프로젝트의 API 문서도 최신화 되어 있지 않았습니다.)

 

 

---

 

API 문서 최신화, 왜 자꾸 하지 않는 걸까?

보통의 개발자는 프로그래밍을 하다가 기존의 설계 문서와 다르게 구현해야 할 때가 종종 생깁니다.

어떠한 기능을 구현해야 할 때 필요한 요소들이 더 추가되거나, 삭제가 될 경우,

Controller 에서 받는 Request가 변경될 수도 있고

어떠한 기능을 통해 얻어오는 데이터의 구조가 변경될 경우,

Controller 에서 뱉는 Response가 변경될 수 있습니다.

 

 

위와 같은 경우에는 코드 상에 비즈니스 로직 구현에서 변경이 이뤄졌기 때문입니다.

로직에 대해 고민, 해결, 프로그래밍 이후에 API 문서를 다시 작성하러 가야 합니다.

 

사전에 있는 작업이 길고, 코드에 집중되어 있습니다.

그렇기에 API 문서로 돌아가는 행위는 코드에서 다소 멀고 잊을 수 있게 됩니다.

 

 

이를 해결하기 위해서는

먄약 API 문서화 작업이 코드에서 이뤄진다면, 다소 먼 작업을 이전 보다 가깝게 둘 수 있습니다.

 

 

---

 

 

그럼 이제 Spring REST Docs를 저희의 현재 상황에서 써야 하는 진짜 이유에 대해 살펴보도록 하겠습니다.

 

 

Spring REST Docs 왜 쓰려고 하는거야?

저희 새롭게 구현하고자 하는 API 에 대해 간략하게 작성해 놨었습니다. DDD를 통해서도 분석하였고 Restful 하게 API URL 을 설계했었죠.

 

그리고 저는 해당 설계를 자세히 작성하는 업무를 맡았습니다.

API 문서를 자세히 작성하기 위해 기존의 프로젝트에 작성된 API 문서를 다시 살펴보았는데요.

API가 최신화 되어 있지 않고 가독성이 좋지 않았습니다.

더불어, 리펙토링을 위해 저희가 설계했던 API 문서에 작성되지 않은 여러 기능도 발견되었죠.

 

 

여기서 저는 이렇게 생각했습니다.

“나름 도메인에 대해 분석하고 기능을 생각해 설계했지만 부족한 API가 있었고, 기존의 API 문서 최신화 실패 선례를 다시 반복하지 않을 것이라는 모든 행위의 완벽함을 확신할 수 없다 ”

 

 

그래서 저는 선례의 실패 요인을 분석했고

실패 요인은 코드와 다소 거리가 있는 API 문서화였습니다.

 

 

결과적으로, API 문서화를 코드를 사용한 Spring REST Docs 로 해결 하고자 합니다.

---

Spring REST Docs ,그게 뭘까?

 

SpringRestDocs는 테스트 코드를 기반으로 스닙펫(코드 단락)을 추출하여 API 문서를 자동으로 만들어줍니다.

그렇기에 SpringRestDocs는 문서화하기 위해서는 Test Code가 필요로 합니다.

 

해당 라이브러리가 API를 문서화하는 과정은 미리 작성된 Controller와 정상 동작하기 위한 TestCode를 통해 코드 스닙펫을 추출하여 이를 통해 문서화를 진행합니다.

 

만약 기존의 설계와 다르게 코드를 변경할 경우, 테스트 코드도 수정하여야 모든 테스트가 성공하게 됩니다.

아래는 Spring REST Docs에서 API 문서화를 위한 테스트 코드 예시입니다.

 

 

위와 같이 작성된 Test Code는 아래와 같은 API HTML 문서화가 됩니다.

 

 

 

++ 편한 Swagger가 있는데, Spring REST Docs를 쓰는 이유도 궁금해!

굳이 Spring REST Docs를 사용하는 이유는, 프로덕트 코드에 침투적이지 않고 작성할 수 있으며 Swagger보다 더 보기 좋게 분리하여 시각적으로 제공할 수 있기 때문이었습니다.

 

 

---

 

결론

API 문서를 Notion을 통해 구체화하고자했습니다.

그러기 위해 기존의 문서를 살펴보니 최신화가 되어있지 않았고, 리펙토링을 위한 저희의 설계 또한 부족한 점이 있었습니다.

 

 

위와 같은 이유로 저는 API 문서를 최신화 하지 못했던 선례에서 이유에 대해 고민했고

결론으로는 코드를 통한 API 문서화가 실수를 최소화할 수 있을 것이라는 답이었습니다.

 

 

그래서, API 문서화를 도와주는 SpringREST Docs를 사용하고자 합니다.

사용하는 방법과 사전에 필요한 설정은 제가 작성해 놓도록 하겠습니다.