api 문서화, 좋은 예시

0.

api 자급자족할 때는 딱히 신경쓰지 않았는데, 간만에 다른 사람이 쓸지도 모르는 상황이 돼서,

api 문서화를 찾아봤다.

1. swagger

https://swagger.io/

이전 회사에서 쓰던 api 문서화 프레임워크.

베트남에 안드로이드/아이폰 어플 만드는 외주를 맡겼었는데 이 swagger가 정말 유용했다.

우리쪽에서 api를 만든 뒤, swagger를 업데이트해서 주면 따로 말로 설명할 필요가 없었다.

다만, 처음 사용이 좀 복잡하고...경우에 따라 작성/수정에 좀 오래 걸릴 수도 있다.

django에 swagger 관련 모듈이 있다!

근데 사용법을 잘 몰라서 몇 번 끼적여보다가 포기.

간지나던데...다음에 다시 도전!

2. Asciidoctor

http://asciidoctor.org/

Asciidoctor

문서 작성을 도와주는 툴인듯 하다.

자세히 읽어보진 않음

3. markdown

https://gist.github.com/iros/3426278

어떤 고마운 분이 깃허브에 markdown 언어로 api 문서화 형식을 올려주셨다.

이크 뭔가 gist로 가져오니 제대로 안 나온다...링크 타고 들어가서 보면 정말 간결하고 깔끔하다.

4. slate

https://github.com/lord/slate

와우!!!!!

내가 찾아헤매던 게 바로 이런 거였다!

깔끔하고 예쁘고 멋지다!!!

다만 윈도우는 지원하지 않는다 해서 ubuntu가 깔려있는 노트북으로 했다.

세팅도 굉장히 간단하고 무엇보다 예쁘다!