5분 안에 구축하는 APIDoc (API 규격서)

apidoc 는 nodejs 로 만들어 졌으며 규격서를 자동으로 만들어주는 도구 이다.

nodejs 이기에 npm install로 설치가능하며 아래 공식 문서 참고하여 진행해본다.

- https://apidocjs.com/

apiDoc - Inline Documentation for RESTful web APIs

apidoc 설치를 진행한다.

$ npm install apidoc -g

정상적으로 설치 되었는지 확인한다.

$ apidoc -v

              _     _
   __ _ _ __ (_) __| | ___   ___
  / _' | '_ \| |/ _' |/ _ \ / __|
 | (_| | |_) | | (_| | (_) | (__
  \__,_| .__/|_|\__,_|\___/ \___|
       |_|                v0.50.4

우선 apidoc 디렉토리를 만들고 그 안에서 진행해보자.

$ mkdir apidoc
$ cd apidoc

프로젝트 description 을 적으며 샘플 코드를 넣었다.

$ vi apidoc.json
{
  "name": "example",
  "version": "0.1.0",
  "description": "apiDoc basic example",
  "title": "Custom apiDoc browser title",
  "url" : "https://api.github.com/v1"
}

구분	설명
name	프로젝트의 이름
version	프로젝트 버전
description	프로젝트 소개
title	브라우저 제목 텍스트
url	API 경로(끝점)의 접두사

규격서 내용은 아래와 같이 샘플코드를 src 디렉토리에 만든다.

$ mkdir src
$ vi src/example.js
/**
 * @api {get} /user/:id Request User information
 * @apiName GetUser
 * @apiGroup User
 *
 * @apiParam {Number} id Users unique ID.
 *
 * @apiSuccess {String} firstname Firstname of the User.
 * @apiSuccess {String} lastname  Lastname of the User.
 *
 * @apiSuccessExample Success-Response:
 *     HTTP/1.1 200 OK
 *     {
 *       "firstname": "John",
 *       "lastname": "Doe"
 *     }
 *
 * @apiError UserNotFound The id of the User was not found.
 *
 * @apiErrorExample Error-Response:
 *     HTTP/1.1 404 Not Found
 *     {
 *       "error": "UserNotFound"
 *     }
 */

규격서 파일을 만들어 본다.

$ apidoc -i src -o apidoc

apidoc 파일이 생성되고 들어가서 보면 index.html 파일이 생성되어 있다.

$ cd apidoc
$ ls
assets		index.html

html 파일을 브라우저에서 열면 아래와 같이 규격서 페이지가 정상적으로 만들어 진것을 볼 수 있다!

만드는 방법은 간단하고 심플하다.

저번시간에 [swagger를 이용해 규격서 생성] 해보았으며 두 도구를 비교해보면 아래와 같다.

구분	apidoc	swagger
처음 구축 난이도	낮다	apidoc 보다 높다
운영	API, 규격서 따로 운영 가능	API 프로젝트에 같이 포함되어 있어 같이 규격서 반영됨
API 추가시 규격서 추가 공수	swagger 보다 높다 (직접 API 명, 응답값을 기재 해야함)	낮다
UI	심플	다채로움
규격서 공유	WEB, 문서로 공유 모두 가능	문서로 따로 공유 가능
위험성	규격서 공유를 문서로 하면 공유 받는 대상만 정보를 알수 있어 다소 위험성은 낮다.	공유하는 규격서 사이트가 외부에 오픈 되어 있다면 아무나 규격서 페이지에 접근해서 볼 수 있어 정보 노출 위험이 있다.
자원 사용도	낮다	apidoc 보다 높다

어떤것이 더 좋다고 지정할 수 없으며 두 도구 모두 쉽게 규격서를 만들수 있다는것은 같다.

개발자와 API 특성, 운영 방법에 따라 맞는 도구를 선택하여 사용하면 될 것 같다.  

끝!