api 문서 작성 보통 어디에 하시나요?

안녕하세요! 제 경험상 API 문서 작성 방법은 각 팀의 상황에 따라 장단점이 있다보니 명확하게 어떤 방법이 좋다 라고 말씀드리기엔 애매한 부분이 있습니다. 제가 지금까지 경험했던 API 문서 작성 방법과 장단점을 말씀드릴테니 질문자님의 상황에서 가장 효율적인 방법을 선택해보시면 좋겠습니다. 1️⃣ Github, Notion, Confluence 등을 사용 📌 장점 - API 가 구현되지 않더라도 미리 작성하여 필요한 부서 혹은 팀원들에게 공유할 수 있습니다. - markdown 문법등을 사용하거나 템플릿을 만들어 자신이 원하는 형태로 문서를 작성할 수 있습니다. - API 문서를 외부에 노출하지 않아야 할 경우 이에 대한 보안 설정이 가능합니다. 📌 단점 - API 변경이 발생할 경우 이에 대한 유지보수도 신경써야 합니다. 만약 유지보수가 제대로 안될경우 버그나 커뮤니케이션 비용이 발생합니다. - API 테스트를 하기 쉽지 않습니다. - 문서 작성 및 유지보수에 적지 않은 시간이 소요됩니다. 2️⃣ swagger 사용 📌 장점 - 소스 코드 기준으로 API 문서를 자동으로 만들수 있어 API 작성에 드는 시간이 줄어듭니다. - API 테스트를 쉽게 할 수 있습니다. - API 가 새로 생기거나 변경사항이 발생할 경우 이와 관련된 문서 변경이 자연스럽게 진행될 수 있습니다. 📌 단점 - API 문서 작성을 위해 소스코드에 서비스기능과 상관없는 내용을 추가해야합니다. - 검증이 되지 않거나 버그가 있는 API 가 문서에 노출될 수 있습니다. - 경우에 따라 API 변경시 이를 swagger 에 반영하기 위한 유지보수가 필요할 수 있습니다.(API 설명이나 파라미터 상세 내용 등) 3️⃣ Spring Rest Docs (Spring 을 사용하실 경우) 📌 장점 - 테스트 코드를 기반으로 문서를 작성하는 형태이기 때문에 swagger 와 달리 소스코드에 불필요한 내용을 넣지 않아도 됩니다. - 테스트 코드 검증이 완료되었을 경우에만 API 문서 작성이 가능하기 때문에 검증된 API 만 문서에 노출 할 수 있습니다. - API 문서를 작성하려면 테스트코드를 작성해야하기 때문에 자연스럽게 테스트 커버리지를 높일수 있습니다. 📌 단점 - API 문서 작성을 위한 테스트 코드를 작성해야하는데 이게 경우에 따라 꽤 많이 작성해야 합니다. - 테스트 코드 실행을 통해 API 문서를 생성하는 방식이기 때문에 실제 API 문서를 노출하려면 따로 웹서버를 띄우고 이를 관리하기 위한 CI/CD 고민이 필요합니다. - Swagger 처럼 API 테스트를 할 수 없습니다. 3️⃣ 안의 단점인 API 테스트를 못하는 부분을 개선하기 위해 Spring Rest Docs 를 Open API Specification 으로 변환하여 Swagger 를 쓸 수 있도록 하는 방법을 정리한 글(https://careerly.co.kr/comments/64189?utm_campaign=self-share)도 있으니 한번 참고해보시면 좋겠습니다. 부디 저의 작은 지식이 도움이 되시길 바라겠습니다.

개인적으로 생각하는 API문서는 Postman 에서 무료로 제공하는 Document를 활용해 보는것을 추천드립니다. 대부분 API 문서는 초기 작성 후 변경 사항이 있을 때 유지보수가 잘 안된다는 단점이 있습니다. 개발시에 API 테스트도 해야되고, 개발 후에 문서 업데이트도 해야되는 상황이 많을 텐데요, Postman 에서는 api collection 이라는 것을 제공하고 있고, 개발 시 api를 쉽게 테스트할 수 있는 기능을 제공하고 있습니다. 테스트 완료 후, 해당 콜렉션의 Document를 publish 하고, 해당 링크를 타팀에 공유만하면, 별도로 문서 업데이트 작업없이 최신 반영된 정보를 공유할 수 있어서 좋다고 생각합니다.

저희팀은 노션이 도큐먼트 허브라서 노션에다가 정리를 합니다.