express - apiDoc 라이브러리로 api 문서 만들기

사용 예시 화면

개요

open api 프로젝트를 진행하던 중 api 문서를 만들 차례가 다가왔고, swagger의 끔찍한 ui를 피하기 위해 어떤 라이브러리를 사용할까 고민하다 apiDoc이라는 간단한 api 문서 생성 라이브러리를 찾아 사용하게 되었다.

apiDoc 공식 Live Demo

---

프로젝트 구조

project/
├── doc/
│   ├── assets/
│   └── index.html
├── src/
│   ├── controllers/
│   │   └── userController.js
│   └── routes/
│       └── userRoutes.js
├── app.js
├── .gitignore
├── apidoc.json
└── package.json

---

apiDoc 사용법

1. 라이브러리 설치

npm install --save-dev apidoc

---

2. apidoc.json 작성

루트 경로에 apidoc.json 파일 작성

{
  "name": "서비스 이름",
  "version": "1.0.0",
  "description": "서비스 설명",
  "title": "타이틀",
  "url": "http://example.com"
}

---

3. api 주석 작성

라우터와 컨트롤러를 사용 중인 경우 예시 코드

const express = require('express');
const router = express.Router();
const userController = require('../controllers/userController');

/**
 * @api {get} /users/:id 유저 정보 조회
 * @apiName GetUser
 * @apiGroup User
 * @apiVersion 1.0.0
 * @apiDescription 특정 ID를 가진 유저의 정보를 조회합니다.
 *
 * @apiHeader {String} Authorization 사용자 인증 토큰 필요
 * @apiHeaderExample {json} 헤더 예시:
 *     {
 *       "Authorization": "Bearer eyJhbGciOi..."
 *     }
 *
 * @apiParam {Number} id 유저의 고유 ID
 * @apiParamExample {json} 요청 예시:
 *     {
 *       "id": 123
 *     }
 *
 * @apiSuccess {Number} id 유저의 ID
 * @apiSuccess {String} firstname 유저의 이름
 * @apiSuccess {String} lastname 유저의 성
 * @apiSuccess {String} email 유저의 이메일 주소
 * @apiSuccess {Object[]} roles 유저의 역할 목록
 * @apiSuccess {String} roles.role 역할명
 * @apiSuccess {String} roles.description 역할 설명
 *
 * @apiSuccessExample {json} 성공 응답 예시:
 *     HTTP/1.1 200 OK
 *     {
 *       "id": 123,
 *       "firstname": "John",
 *       "lastname": "Doe",
 *       "email": "john.doe@example.com",
 *       "roles": [
 *         { "role": "admin", "description": "관리자" },
 *         { "role": "user", "description": "일반 사용자" }
 *       ]
 *     }
 *
 * @apiError UserNotFound 유저를 찾을 수 없음
 * @apiError InvalidID 잘못된 ID 형식
 *
 * @apiErrorExample {json} 오류 응답 예시:
 *     HTTP/1.1 404 Not Found
 *     {
 *       "error": "UserNotFound",
 *       "message": "사용자를 찾을 수 없습니다."
 *     }
 *
 * @apiExample {curl} Curl 사용 예:
 *     curl -i http://localhost/users/123 -H "Authorization: Bearer eyJhbGciOi..."
 */
router.get('/users/:id', userController.findUser);

module.exports = router;

---

apidoc 문서 생성

npx apidoc -i 라우터 디렉토리 경로

# npx apidoc -i /src/routes/

---

app.js에 doc 미들웨어 추가

const express = require('express');
const path = require('path');
const app = express();
const userRoutes = require('./routes/userRoutes'); // 예시 라우터

app.use('/api-docs', express.static('doc'));
app.use('/user', userRoutes);

app.listen(3000, () => {
  console.log('Server is running on port 3000');
});

---

완료!

 

GitHub - Aleph-Kim/apiDoc-example: apiDoc 라이브러리 사용 예시

 

---

참고

apiDoc - Inline Documentation for RESTful web APIs

 

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

 

 

---

추가

위 방식으로만 진행할 경우 api 문서를 갱신할때 매번 수동으로 명령어를 입력해야하는 번거로움이 있다.
이를 해결하기 위해 근본 nodemon 라이브러리를 사용하여 자동으로 api 문서가 갱신되게 해보았다.

nodemon 설치

npm install --save-dev nodemon

---

package.json에 api 문서 자동 갱신 스크립트 추가

{
  "name": "test",
  "version": "1.0.0",
  "main": "index.js",

  ~~~

  "scripts": {
    "api-docs": "nodemon -L --watch src/routes --watch apidoc.json --ext js --exec \"apidoc -i src/routes -o doc/\"",
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  ~~~

  "devDependencies": {
    "nodemon": "^3.1.4",
    "apidoc": "^1.2.0"
  }
}

---

실행

npm run api-docs

---

완료

이제 src/routes 디렉토리에 위치한 파일이나 apidoc.json 파일이 수정될때마다 api 문서가 자동으로 갱신된다.