티스토리 뷰

API 문서 작성 방법의 변화

  • API 레퍼런스 문서를 작성하는 가장 원시적이면서 일반적인 형태는 리비전이 발생할 때마다 마이크로소프트 워드 파일을 직접 작성하여 클라이언트에게 배포하는 것이다. 국내 개발자들에게 가장 익숙한 방식이기도 하다.

  • 현재 가장 유행하는 형태는 첫번째, API 문서 작성 포맷을 규정하고, 두번째, 그 포맷에 맞게 텍스트 파일을 작성하면, 세번째, 렌더러를 통해 멋지게 화면에 뿌려주는 것이다. API를 구현한 언어적 특성에 따라 두번째 방법이 소스 코드 상에서 자동화되기도 한다. 현재 무료로 공개된 대부분의 오픈 소스 API 문서 작성 도구들은 이러한 패턴을 따른다.

  • 한편 렌더러 측면에서 최근 가장 보편적인 화면 구성 레이아웃은 화면을 3등분한 3패널 디자인이다. 좌측에는 메뉴를, 중앙에는 각 API에 대한 설명과 스펙을, 마지막으로 우측에는 각 API의 요청 및 응답 예제를 기술하는 것이다. 이러한 흐름을 충족하는 무료 도구들을 아래 소개한다.

Slate

  • SlateMarkdown 기반의 문서 포맷과 반응형 렌더러를 함께 제공한다. 문서 포맷이 직관적이고 단순하여 학습 난이도는 가장 낮은데 반해 결과물이 세련되어 쓸만하다. 가장 적은 노력으로 그럴듯한 결과를 보여준다.
  • 1개 테마와 3패널 디자인만 제공한다. 모바일 디바이스에서는 좌측 메뉴 패널이 사라지고 버튼으로 대체된다.
  • Slate에 관해서는 따로 설명한 이 있으니 참고한다.

API Blueprint

  • API BlueprintSlate와 유사한 Markdown 기반의 문서 포맷을 제공한다. 학습 난이도는 Slate보다 높지만 그만큼 문서로 표현할 수 있는 범위가 다양하다.

  • 현재 최신 스펙은 Format 1A revision 9이다.

  • API Blueprint는 렌더러를 따로 제공하지 않는다. 하지만 Aglio라는 써드파티 렌더러가 역할을 대신한다.

  • Aglio 렌더러는 5개 테마와 2, 3패널 디자인을 제공한다. 모바일 디바이스에서는 좌측 메뉴 패널이 사라진다.(버튼으로 대체되지 않는다.)

Swagger

  • Swagger는 가장 유명하고 역사가 깊은 API 문서 도구이다. JSON(RAML도 지원) 기반의 문서 포맷을 제공한다.

  • 그 명성 때문에 국내에서도 API 문서 자동화를 추진할 때 가장 먼저 시도되지만 가장 도입 실패 사례가 많기도 하다. 이유는 단순한 문서 작성 도구를 떠나 스펙 차원에서 상당히 엄격한 REST API 설계 철학을 강제하기 때문에 이를 준수하지 못하는 API 서비스는 아예 사용을 포기할 수 밖에 없다.

  • 자체적인 렌더러로 Swagger UI를 제공하지만 보다 유명한 것은 ReDoc 반응형 렌더러이다. 3패널 디자인을 제공한다.

참고 글

댓글
최근에 올라온 글
최근에 달린 댓글
Total
Today
Yesterday
링크
«   2024/03   »
1 2
3 4 5 6 7 8 9
10 11 12 13 14 15 16
17 18 19 20 21 22 23
24 25 26 27 28 29 30
31
글 보관함