[BE/Node.js] apidoc으로 api document 만들기

💬 머리말

apidoc을 알게 된 건 지금 스프링으로 프로젝트를 진행하고 있는데 스프링에는 API document 를 자동으로 적용해주는 Swagger가 있는 걸 보고 npm 에도 당연히 있겠지 싶어서 찾아봤는데 역시 있길래 바로 적용 결정.

(역시 킹PM)

 

 

---

🏃 시도

🌟 apidoc은 global 로 설치해야 apidoc 명령어가 작동한다!! 이점 유의!!

# apidoc 설치
npm install apidoc -g

# '-i' + 'api 탐색하려는 디렉토리 위치'
# 우리 프로젝트의 경우 route 연결이 ./index -> ./route/
# 구조라서.. 디렉토리 하나만 추가하기엔 없어보여서 그냥 전체 디렉토리로 연결!
# '-o' : 만든 apidoc html 파일을 저장해놓을 저장 위치
apidoc -i . -o public/

 

📄 apidoc.json

• 루트 경로에 이 파일을 만들어줘야함

{ 
  "name": "OPEN API",
  "version": "1.0.0", 
  "description": "open api 오신것을 환영합니다.",
  "title": "OPEN API",
  "url": "<http://localhost/api>",
  "sampleUrl": "<http://localhost/api>",
  "order": [  
    "공통", "주문", "작업"
  ]
}

 

📄 index.js

• http 요청 쿼리문이 있는 파일에 해당 부분 붙여넣음
• 주석까지 통째로!
  • 저 @ 가 스프링의 어노테이션하고 비슷한 역할인 것 같다

/**
 * @api {get} /user/:id Request User information
 *
 * @apiVersion        1.0.0
 * @apiName GetUser
 * @apiGroup User
 *
 * @apiParam {Number} id Users unique ID.
 *
 * @apiSuccess {String} firstname Firstname of the User.
 * @apiSuccess {String} lastname  Lastname of the User.
 */

 

 

---

⚠️ 문제

웹 서버에 배포하려는 데 문제가 발생했다.

우리 서버 주소를 꽁꽁 숨긴 답시고 apidoc 빌드 파일도 localhost 인 상태로 빌드해서 올렸더니

Request Sample Url도 이렇게 뜨는 것이었다.. 😂

 

결국.. EC2 서버에도 apidoc을 설치했는데

aㅏ... 인코딩 문제..(node_modul 설정 파일 자체를 건드려야하는. + 고생을 곁들인)

이건 도저히 해결할 수 없겠다고 판단이 들어서.. 그냥 FTP 로 빌드 파일만 덮어쓰기 하기로 결정..!

 

 

---

✨ 해결

우리 서버 주소로 바꾸고 다시 api-doc 빌드한 다음에 이 main.bundle.js 번들 파일만 바꿔줬다.

(여차저차 무식한 방법으로) 해결완료 !

 

 

---

🔗 참고

• APIDoc 으로 REST API 문서화 하기(REST API documentation) #1
• apiDoc - Inline Documentation for RESTful web APIs
• APIDOC

 

 

---

💡 깨달은 점

• 기존에는 passport를 이용한 로그인 로그아웃 여부를 루트 페이지에서 조회했었는데, apidoc이 루트 파일에서 열려서 어쩔 수 없이 /auth 의 하위로 옮기게 되었다.
  • 이렇게 하는 게 훨씬 가독성도 좋고 RESTful API에 맞는 거라는 걸 알게 되었다.
  • 그룹화하는 게 관리측면에서도 매우 좋다!