[Koa] Koa에서 apidoc 사용하기

Swagger보다 가볍고, 설치가 쉬운 apidoc을 Koa에서 사용해보겠습니다. 직접 API와 응답을 기재해야 하기 때문에, 작은 프로젝트에서 적합할 것으로 생각됩니다.

npm install apidoc -g

우선 전역으로 apidoc을 설치해준 후, 프로젝트 루트 디렉토리에 apidoc.json이라는 설정 파일을 만들어 다음 내용을 작성해줍니다.

{
  "name": "이름",
  "version": "1.0.0",
  "description": "페이지 설명",
  "title": "페이지 제목",
  "url": "http://localhost:4000/apidoc"
}

그 후 apidoc이 읽어올 파일에

/**
 * @api {get} /api/user/:id Request User by ID
 *
 * @apiVersion 1.0.0
 * @apiName GetUser
 * @apiGroup Users
 *
 * @apiParam {String} id ex) `asd32j`, ...
 *
 * @apiSuccess {String} name
 * @apiSuccess {Number} age
 */

주석으로 이렇게 API 명세를 작성해주면 됩니다.

packages.json의 서버 실행 스크립트에 다음 줄을 추가해서 서버가 실행될 때마다 apidoc을 갱신해주도록 합니다.

apidoc -i src/api -f \".*\\.controller.ts\" -o public/apidoc

src/api 폴더 안의 *.controller.ts 파일을 읽어와서 public/apidoc 위치에 문서를 만든다는 뜻입니다.

Koa에서 정적 파일을 serve하기 위해 koa-static 패키지를 설치한 후

import serve from "koa-static";

app.use(serve("./public"));
app.use(serve("./public/apidoc"));

이렇게 작성해준 후 /apidoc 라우트에 들어가보면

잘 뜹니다.