개발 프로젝트 명세서 작성하기 (기능명세서, API 명세서)
Skala 과정에서 마이크로 서비스 아키텍처 구조에 대해 새롭게 알게 되었습니다.
배운 것을 실제로 구현해보기 위해 이 여정을 시작하기로 했습니다.
처음 글부터 보러가기
뗄레야 뗄 수 없는 문서 작업,,ㅜㅜ
사실 스웨거, Postman을 이용하면 API 명세서는 굉장이 간단하게 작성할 수 있습니다.
그치만 gradle에서 스웨거를 설정하는건 익숙하지만 maven 환경은 dependency가 뭔가 다르더라구요..?
굳이 작성해야하나요? 귀찮은데..
예전에 비전공자 분들과 팀프로젝트를 진행한 적이 있었는데,
기획자 분에게 기능명세서를 작성해달라고 요청했더니 제대로 된 레퍼런스가 없어서 그런지 제가 원하던 방향으로 문서가 작성되지 않았습니다,,
결국 디자이너 분이 디자인 하신 초안을 보고 기능을 구현하다보니
기획자 분의 정확한 기획 의도와는 다르게 디자인이 되었는지 계속해서 요구사항이 바뀌어서..저도..프론트도..계속해서……수정을………했던 기억이 있습니다…..
물론 지금은 혼자서 진행하는 프로젝트이지만 문서를 작성하지 않으니
내가 어디까지 API를 만들었고, 그 API가 어떤 기능을 하며 Request와 Response가 무엇인지 한 눈에 확인하기가 어려웠습니다,,(이것만 파악하려면 진짜 물론 스웨거를 사용하는 것이 훨씬 편합니다)
그래도 스웨거의 한계는 따로 백엔드에서 설명을 붙이지 않는 한 권한이 어떻게 설정되어 있는지 확인하기가 어렵습니다.
또한, 앞으로 개발하게 될 기능에 대한 부분은 전혀! 없습니다.
설명이 없으면 해당 API가 어떤 기능을 수행하는지도 파악하기 힘듭니다,,
그래서 작성하게 되었습니다!
노션을 활용합니다
기획명세서
사실 조금 더 바람직한 구조는 다음과 같습니다.
혼자 작성하는거라 알아듣기만 하면 되기 때문에 주기능과 상세기능까지는 작성하지 않았습니다 (ㅎㅎ)
저렇게 기능, 세부기능, 기능에 대한 설명, 구현 상태를 상세하게 기술하면 개발을 할 때 네비게이션을 켜두고 개발을 하는 기분(?)이 듭니다
내가 어디까지 했고, 뭘 더 해야하는지가 명확하게 보여서 동기부여도 확실하게 되는 것 같습니다
API 명세서
아무래도 이 명세서는 프론트와 백엔드 간의 문서라고 봐도 무방할 것 같습니다.
사실 API 명세는 스웨거로 확인해도 충분하지만,,권한 확인을 위해,,
그리고 팀 단위로 프로젝트를 진행하다보면, 누가 어떤 부분을 담당할지도 한 눈에 확인할 수 있어서
문서화하는 것이 꼭 “필요없는데 귀찮게하는” 과정만은 아닙니다
API 명세는 다음과 같이 작성합니다.
Swagger UI
Postman
API 명세서는 Swagger 나 Postman 을 이용하는 것이 자잘한 오타나 변수명 오류가 안 생길 수 있습니다!
마치며
다음은 마이페이지 에 보일 정보들을 Aggregation을 통해 조합하는 기능에 대한 글을 작성해보겠습니다 😀
참고 자료