APIDOC

Rony·2021년 6월 1일

api 를 만들고나서 해당 api 의 가이드 문서를 작성하는 일은 상당히 번거로운 일이다.
html 코드를 이용해 한땀한땀 만들어 주거나 엑셀을 통해 api 가이드를 제공할수 있지만 코드상의 간단한 주석을 통해 자동으로 api 문서를 생성해주는 모듈이 있다.
대표적으로 swagger 와 apidoc 인데...
개인적으로는 디자인이 더 깔끔하다고 생각되는 apidoc 에 관해 내용을 적어보도록 하겠다.

apidoc 는 프로젝트 코드상에 apidoc 규칙에 따라 주석을 남기면 해당 주석을 바탕으로 api 문서를 자동 생성해주는 문서화도구이다.

apiDoc - Inline Documentation for RESTful web APIs

적용예시

설치

전역으로 설치해주고나면 바로 사용이 가능하다.
```
npm install apidoc -g
```

기본설정

apidoc 설치후 root 경로에 apidoc.json 파일을 만들어 기본설정을 한다.

```json
{ 
  "name": "OPEN API",      // api 이름
  "version": "1.0.0",                   // 현재 적용중인 버전
  "description": "open api 오신것을 환영합니다.", // api 설명
  "title": "OPEN API",     // 브라우저 상단 탭에 노출될 제목
  "url": "http://openapi.io/api/",  // 정의되는 액션에 기본으로 사용되는 도메인
  "sampleUrl": "http://openapi.io/api/",  // 테스트호출을 할수 있도록 해주는 설정 및 테스트 호출 도메인 ( 해당 값을 넣지않으면 테스트 호출을 할수 없다 )
  "order": [   // 문서 왼쪽 트리 정렬순서
    "공통", "주문", "작업"
  ]
}
```

위의 설정중 sampleUrl 은 테스트 호출을 해볼수 있도록 제공해주는 부분으로 테스트 호출을 지원하지 않으려면 sampleUrl: null 로 설정해주어야 한다.
(문서와 api 의 도메인이 다른경우 셈플 호출이 지원되지않으니 셈플호출 지원을 하고 싶다면 문서와 api 의 도메인을 동일하게 셋팅해주도록 하자. )

문서 생성

문서생성은 다음의 명령을 실행 함으로써 진행된다.
```
apidoc -i src/ -o public/
```
-i 옵션은 문서생성을 위해 파일을 체크해야할 경로이고

-o 옵션은 만들어진 문서를 생성할 폴더이다.
액션히어로는 기본적으로 public 폴더에 생성된 파일정보를 문서로 보여주기 때문에 public 폴더에 생성하도록 한다.
playauto2.0 open api 에서는 해당 명령어를 package.json 에 script 로 작성해서 사용한다.
```
npm run apidoc
```

템플릿

문서의 기본 UI 가 밋밋하게 느껴진다면 템플릿을 적용하여 UI 를 바꿔볼 수 있다.
github 에 apidoc 로 검색을 하면 여러개의 템플릿이 나오는데 그중 아래의 템플릿이 모양이 제일 깔끔하게 보이기 때문에 해당 템플릿을 사용하도록 하자.

marciotoze/dash-apidoc-template
템플릿을 사용하려면 해당 템플릿 코드를 프로젝트 폴더내부에 다운로드 받고 문서생성 cli 에 사용템플릿을 추가해주어야 한다.
기본적으로 사용 프로젝트 내에서 위의 템플릿을 git clone 받은다음 api 문서 생성 cli 명령어를 다음과 같이 수정해준다.
```
apidoc -i src/ -o public/ -t dash-apidoc-template/template
```
하지만 위와 같이 dash-apidoc-template 을 바로 clone 받아 사용할경우 해당 코드가 프로젝트 git 저장소에 올라가지 않기 때문에
dash-apidoc-template 폴더내부의 template 폴더만 복사해서 프로젝트에 넣어주고 명령어를 다음과 같이 수정하면 프로젝트 저장소에 템플릿 코드가 정상적으로 업로드 되니 참고하자.
```
apidoc -i src/ -o public/ -t template
```

주석

Example >

/**
 * 주문삭제
 * 
 * @api {delete} order/delete 주문삭제
 * @apiName 주문삭제
 * @apiGroup 주문
 * @apiVersion 1.0.0
 * @apiDescription 주문정보를 삭제합니다.
 * 
 * @apiHeader {String} Authorization 인증토큰
 * @apiHeaderExample {json} Header (example):
 * {
 *   "Authorization": "Token eyJhbGciOiJIUzU......"
 * }
 * 
 * @apiParam {String[]} uniqList 주문해시값
 
 * @apiParamExample {json} Request (example): 
 * {
 *   "uniqList": [
 *     "7432132435432",
 *     "4657432132121"
 *   ]
 * }
 * 
 * @apiSuccess {String} results 성공, 실패여부
 * 
 * @apiSuccessExample {json} Response (example):
 * {
 *   "result": "success"
 * }
 * 
 * @apiError error 에러내용 확인
 * 
 * @apiErrorExample {json} Error (example):
 * {
 *   error: "출력되는 에러메세지"
 * }
 * 
 */