협업의 기본, API 문서 만들기!

요구사항

API 문서 작성

API 문서 툴 선정

API 문서를 만드는 다양한 툴이 존재합니다.

• Slate
• API Blueprint
• Swagger (or Spring REST doc)
• GitBook
• Notion
• Github Wiki
• ...

이중에서 저는 GitBook을 선택하게 되었습니다.

• git처럼 commit,merge가 존재하여 문서 버전을 관리할 수 있다.
• 테스트 요청 및 응답은 불가하지만 지금은 학습의 단계이기 때문에 필요성이 크지 않다.

Swagger 사용을 고민해보았지만, 코드가 지저분해질 수 있고
아직 API 문서 자동화까지 해볼 순 없었습니다.

API 문서 필수 작성 리스트

• URL 주소 / HTTP 메서드
• API 설명
• 요청 형태
  • Path Parmas
  • Query Params
  • Body Params
  • 필수 여부
  • 데이터 타입
• 응답 형태
  • 응답 코드(status code)
  • 각 응답 코드별 설명
  • 응답 형태 (response value)
  • 응답 값에서 각 파라미터의 의미
  • 응답 값에서 각 파라미터의 필수 여부
  • 응답 값에서 각 파라미터의 데이터 타입

구현

https://jscode.gitbook.io/jscode/
해당 사이트로 구현을 완료하였습니다.

API 문서에 대한 개요와 사용법, 그리고 구체적인 API 문서로 이루어져 있습니다.

API 문서 안에는 위의 필수 작성 리스트에 따라 작성하였습니다.
Gitbook에서는 미리 UI적으로 리스트를 제공해주어 편리하게 작성할 수 있었습니다.

Gitbook 장점

UI가 직관적이고 이쁩니다.

Gitbook 단점

온라인 환경에서 편집하다 보니 글자가 짤리고 없어지는 등의 오류가 발생합니다. 특히 한글 입력 시 해당 오류가 자주 발생하여 작성하는데 시간이 더 소요됩니다.