Apiary.io api 문서 작성법

Apiary 간단 소개

Apiary 는 널리 쓰이는 API 문서화 도구이다. 내가 다니는 회사에서도 협력업체에 배포하는 API 연동정의서를 Apiary로 작성해 공유하고 있다.(깃허브 등과 연동하지 않고 단순히 문서용으로만 활용해도 엑셀로 작성해 공유하는 것에 비하면 장점이 많은 거 같다. 문서가 최신버전인지를 끊임없이 확인해야할 필요가 없다든가.)

몇년 전 Oracle에 인수됐지만, 여전히 무료로 사용할 수 있다. (물론 무료 버전만으로는 문서를 private하게 만드는 등의 몇몇 기능들은 이용할 수 없다. private하지 않다는 것은 누군가가 해당 문서의 URL만 알면 누구나 접속해서 문서를 열람하는 것을 막을 수 없다는 뜻이다.)

이 글을 쓰게 된 이유

회사에서 Apiary API 가이드를 새로 작성해야할 일이 생겼는데, 기존 문서에 대한 권한도 없고 가르쳐줄 사람도 없어 혼자 검색하다보니 한글로 된 정보는 아직 많지 않은 듯했다. 나중에야 알게 된 사실은, apiary 작성법이나 문법이 아니라 API blueprint 문법이라고 검색해야 했다는 사실이다. 그럼 간단하게 좋은 정보를 (한글로도) 많이 찾을 수 있다.

간단한 apiary(API blueprint) 에디터 문법

기본적으로 마크다운 문법이고 API blueprint 문법이다. 언제나 그렇듯, Apiary의 기능이나 API blueprint 문법에 대해 공식문서를 보면 대부분의 궁금증을 해결할 수 있다. https://apiblueprint.org/documentation/tutorial.html
단, 영어로 돼있다.

오늘 처음 봤더라도 그리 어렵지 않게 배울 수 있다. 일단 Apiary에서 API를 생성하면 아래와 같이 GET과 POST method를 하나씩 포함한 예시문서를 주기 때문에, 여기서 해당하는 부분만 바꿔가면서 작업하면 금방 원하는 걸 만들 수 있다.

혹시 이미 참고할 apiary 문서 URL을 갖고 있다면, 좌측상단위 Download 버튼을 눌러 해당 문서가 어떻게 작성됐는지를 다운받아 볼 수 있고 그대로 복사해서 넣을 수도 있다.(.apib 확장자로 다운로드 되는데, 윈도우의 경우 메모장으로 열면 된다.)

기본으로 만들어주는 예제에 표와 Path Variable은 없는데, 아래와 같이 만든다.

1. 표 만들기(마크다운 문법, velog와 같다)

|표|테스트|
|--|---|
|마크다운|표는|
|이렇게|만듭니다

2. Path Variable 입력법

## Questions Collection [/questions]
위와 같이 입력하면 아래의 붉은색 동그라미 부분이 생긴다.

이 버튼을 누르면 우측에 아래와 같이 뜨게 된다.(앞부분 URL은 문서 최상단에서 HOST: https://polls.apiblueprint.org/ 와 같이 정의돼있다)

이 뒤에 question_number라는 데이터를 Path Variable로 받는다면 아래와 같이 작성하면 그림처럼 Path Variable이 붉은색으로 표기된 문서를 얻을 수 있다.
## Questions Collection [/questions/{question_number}]