안녕하세요! 제 경험상 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)도 있으니 한번 참고해보시면 좋겠습니다. 부디 저의 작은 지식이 도움이 되시길 바라겠습니다.

다음 내용이 궁금하다면?

또는

이미 회원이신가요?

2023년 2월 23일 오후 3:00

 • 

저장 274조회 6,441

댓글 0

    함께 읽은 게시물

    매일의 루틴을 갖는다는 것

    ... 더 보기

    루틴이 있었던 시절

    K리그 프로그래머

    루틴이 있었던 시절

     • 

    댓글 1 • 저장 16 • 조회 4,579


    회피를 해야 할까요? 방안을 찾아야 할까요?

    팀이나, 파트등의 조직에서의 생활을 하다 보면은 나의 의사와 다른 상황이 펼쳐지는 일이 꽤 많은 빈도로 발생이 되는거 같아요. 짧다면 짧고, 길다면 긴 조직 생황을 하였지만 가장 어려운 것이 나의 의사와 다른 생각을 가지는 일들이 생기는 것들 같아요.

    ... 더 보기


    AI에게 코딩을 잘 시키려면 아주 정확하게 스펙을 줘야하는데(앞으로도 그럴 것), 스펙을 작성하는 것 보다 내가 코드를 쓰고 그걸로 스펙을 작성하라고 하는게 더 빠른게 문제..🫠


    올해로 개발자 생활이 햇수로 20년째다

    2005년 7월에 일을 시작했으니, 올해로 개발자 생활이 햇수로 20년째다. 중간에 공백이 조금씩 있었으니 꽉 채운 스무 해는 아니지만, 숫자가 주는 무게는 여전하다. 20년이라는 시간이 흘렀다는 사실이 새삼 신기하게 느껴진다.

    ... 더 보기

    어제 저커버그 인터뷰에서 연구자들을 돈으로 매수..아니 돈으로 경쟁사들에게서 빼오고 있다는 의혹에 대해서 답했는데요.


    이는 잘못된 말이라며, 탑티어 연구자들의 욕망(!)은 GPU를 최대한 많이 사용할 수 있기를 바라는 것이고, 그래서 작은 팀으로 무한대의 GPU를 쓸 수 있게 해 준다는 것으로 유혹(?) 했다고 합니다. (*욕망, 유혹 같은 표현을 저커버그가 쓴 건 아님)


    ... 더 보기

    조회 980