API 문서화 공부하기 - 8 깃북과 마크다운으로 API 문서 정리하기

1 - 7 포스팅을 통해 API에 대해서 공부해보았다. 공부한 내용을 바탕으로 작성한 Surfreport 예시를 이미 익숙한 툴인 깃북과 마크다운 문법으로 정리해보려고 한다. API가이드를 작성할 때 자주 사용되는 툴로는 Swagger와 앞서 잠깐 살펴보았던 Postman도 있다. 아직 본격적으로 사용해보지는 않았지만 API에 대해서 공부하면서 언젠가 사용해볼 기회가 있지 않을까?_?

---

gitbook

먼저 깃북에서는 API를 작성할 수 있는 블록을 제공한다. API Method를 클릭하면 아래와 같은 블록이 생성된다. 이 블록에 입력 값을 입력만 해주면 이제까지 봤던 API문서의 형태로 정리할 수 있다.

출처: 본인

요새 깃북을 사용해보고 있어서 깃북을 통해 정리해보려고 했다. 하지만 깃북을 사용하다 보니 다른 툴을 사용해야 되나 고민이 든다. 단락에서 텍스트를 작성할 때는 크게 문제가 없지만 표 또는 API 블록에서 한글이 제대로 입력되지 않는 오류가 발생하고 있다. 😥 검색해보니 한글 입력 시 오류가 꽤 자주 발생하고 있는 것 같다.

표 입력에서 불편함을 느껴...깃북으로는 매개변수 파트만 간단하게 작성해보았다. 

출처: 본인

 

마크다운

다음은 Atom으로 마크다운을 사용해 작성해보았다. Atom에서는 오른쪽의 미리보기를 제공해 쉽고 편리하게 글을 작성할 수 있다. 마크다운 문법은 아주 쉽기 때문에 조금만 익히면 금방 사용할 수 있다. 물론 거기에 html과 css를 곁들인다면 더 예쁘고 보기 좋은 형태의 문서로 정리할 수 있다. 그래서인지 테크니컬 라이터 채용공고에도 마크다운+html+css사용경험을 우대하는 경우도 많다. 

출처: 본인

마크다운으로 작성한 예시이다. 이전보다 조금 더 다듬어보았고 작성하다 보니 궁금한 점도 많이 생겼다. 틀린 부분도 있겠지만 다른 사이트에서 참고만 하던 API가이드를 직접 작성해보니 어떻게 써야 하는지, 왜 이렇게 써야 하는지를 알 수 있었다. 

참고로 티스토리에서도 마크다운 형식으로 작성이 가능하지만 일부 기능은 지원하지 않는다. git 또는 velog에서 보이는 것처럼 예쁘게 마크다운 형식을 적용하려면 추가 작업을 해야 하기 때문에 이미지로 가져왔다. 

---

여기까지 하고 나니 튜토리얼을 완수한 것 같다! 앞으로도 공부할게 많다. 🙄