API 문서화 하기(ApiDoc)

프로젝트를 진행하면서 개발문서에 API를 작성했다. 하지만 보기도 불편하고 형식도 내 마음대로 작성하기 불편했다.

그래서 다른 방법이 없나 찾아보다가 ApiDoc이라는 API 문서화 프로그램을 알게 되었다.

Apidoc이란?

먼저 apidoc는 nodejs로 만든 API 문서화 프로그램으로 소스 코드내에 정해진 포맷에 맞게 기술하면 API 문서로 만들어준다.

무겁고 사용이 불편한 swagger 에 비해서 설정과 사용이 쉽다고 한다.

Apidoc 사용방법

1. npm global로 apidoc 을 설치한다.

npm install apidoc -g

설치가 되었다면 apidoc -v로 확인했을때 이런 그림을 볼 수 있다.

2.프로젝트 루트 폴더에 apidoc.json 를 만들어 준다.

apidoc.json

{
  "name": "my project",
  "version": "1.0.0",
  "description": "my project apiDoc basic example", 
  "title": "Custom apiDoc browser title", 
  "url" : "https://myproject.example.com/v1" //서버 url
}

3. 이제 src에 각각의 api에대한 내용을 작성한다.

아래는 내가 작성한 주문 api이다

src/order.js

/**
 * @api {post} /order 상품 주문
 * @apiName order
 * @apiGroup Order
 *
 * @apiHeader {String} Authorization 인증토큰
 *
 *
 * @apiSuccessExample Success-Response:
 *     HTTP/1.1 201 CREATED
 *     {
*           "receiver":"홍길동", 
            "phoneNumber":"01012341234",
            "payment":"20000",
            "totalPrice":"17000",
            "deliveryFee":"3000",
            "deliveryRequest":"안전 배송해주세요",
            "zipCode":"123", 
            "roadAddress":"서울", 
            "detailAddress":"아리랑로", 
            "orderProductDtos": 
                "{" 
                    "productId":"1", 
                    "optionId":"1", 
                    "quantity":"2"
                "}" 
 *     }
 *
 * @apiError BlankPhoneNumber 받는 분 번호 미입력
 *
 * @apiErrorExample Error-Response:
 *     HTTP/1.1 400 Bad Request
 *     {
 *       "error": "받는 분 번호를 입력해주세요"
 *     }
 * 
 * @apiError BlankReceiver 받는 분 성함 미입력
 *
 * @apiErrorExample Error-Response:
 *     HTTP/1.1 400 Bad Request
 *     {
 *       "error": "받는 분 성함을 입력해주세요"
 *     }
 * 
 * @apiError BlankAddress 받는 분 주소 미입력
 * 
 * @apiErrorExample Error-Response:
 *     HTTP/1.1 400 Bad Request
 *     {
 *       "error": "받는 분 주소를 입력해주세요"
 *     }
 */

코드 작성은 이 사이트를 참고했다. https://www.lesstif.com/software-architect/apidoc-rest-api-rest-api-documentation-1-98926722.html

문서화

문서화할 source code 경로를 -i 옵션으로 지정하고 생성할 문서 경로를 -o 옵션으로 지정한다.

다음은 프로젝트 문서를 생성하는 명령어 예제이다.

apidoc -i src -o apidoc

명령어 사용후 apidoc/index.html 파일을 열면 이런 화면을 볼 수 있다.

api를 문서화 프로그램을 이용해 작성해봤는데 생각보다 디자인도 괜찮고 작성방법도 어렵지 않았다.

그렇다고해도 이전에 작성해둔 문서를 옮기려면 시간이 좀 걸릴 것 같긴 하다. 남은 부분들은 천천히 시간을 내서 작성해보자