APIDoc 으로 REST API 문서화 하기(REST API documentation) #1

Owned by 정광섭
Last updated: 2021-Dec-06
3 min read


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


무겁고 사용이 불편한 swagger 에 비해서 설정과 사용이 쉽고 괜찮은 결과가 나와서 애용하고 있습니다.


기본 사용

npm global로 apidoc 을 설치합니다.

npm install apidoc -g


프로젝트 루트 폴더에 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"
}

version 이 1.0.0 보다 낮으면 API 문서에 접근할 경우 무한 로딩하니 주의하세요.


이제 문서화할 소스 코드를 하나 생성하고 다음과 같은 샘플 API 문서를 넣어줍니다.

예로 저는 laravel 을 사용하므로 메인 소스가 있는 app 폴더에 아래와 같은 하이 폴더를 만들어 줍니다.

mkdir -p src/Api/v1


API 를 문서화할 파일(예: src/Api/v1/AwesomeApi.js) 를 만들어서 다음 내용을 넣어줍니다.

/**
 * @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.
 */


문서화

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

다음은 laravel 프로젝트 문서를 생성하는 예제입니다.

apidoc -i src/ -o public/apidoc


이제 public/apidoc 이라는 폴더에 static html 파일이 생성되었으므로 serve 를 사용해서 웹 서버를 띄우고 브라우저로 접속하면 됩니다.

serve public/apidoc



확장자 지정

특정 확장자를 가진 파일만 문서화할 경우 -f 로 파일의 확장자를 정규식으로 지정해 줍니다.

아래는 .js파일만 스캔해서 문서화하는 예제입니다.

apidoc -i app/ -f ".*\.js$" -o public/apidoc


템플릿 사용

템플릿을 별도로 사용하려면 -t 옵션으로 템플릿을 지정할 수 있습니다.

apidoc -i app/ -f ".*\.js$" -o public/apidoc \
	-t mytemplate/


제외 파일 지정

-e 옵션으로 제외할 파일을 지정할 수 있습니다.

아래는 AdminController.js 와 ResetPasswordController.js 파일을 제외하고 문서화합니다.

apidoc -i app/ -f ".*\.js$" -o public/apidoc \
	-t mytemplate/  \
	-e AdminController.js	\
	-e ResetPasswordController.js


script 사용

매번 동일 명령어를 입력하지 말고 스크립트로 만들어 놓으면 편하게 사용할 수 있습니다.


아래는 power shell 용 스크립트인 gen-apidoc.ps1 으로 power shell 은 multi line 을 ` (back quote) 로 사용합니다.

# npm i -g apidoc

apidoc -i app/ -f ".*\.js" -o public/apidoc `
        -e AdminController.js `
        -e ResetPasswordController.js

if ($?) {
    serve public/apidoc
}


Linux 용 shell script 는 확장자를 정규식으로 사용하기 위해 . 을 \\. 으로 기술해야 합니다.

#!/usr/bin/env bash

apidoc -i app/ -f ".*\\.js$" -o public/apidoc \
        -e AdminController.js \
        -e ResetPasswordController.js

if [ $? -eq 0 ]; then
    serve public/apidoc
fi


문서화

상세 사용법은 APIDoc 으로 REST API 문서화 하기 #2 참고하세요.


Trouble Shooting

Nothing to do

아래 메시지가 나오고 api 문서가 생성되지 않는 경우 apidoc tag 로 문서화가 안 되어 있어서 발생하므로 apidoc 형식에 맞게 문서화합니다.

$  apidoc -i app/ -f ".*\.php$" -o public/apidoc

{"message":"Nothing to do.","level":"info"}


무한 로딩

Apidoc 으로 생성한 문서 사이트가 무한 로딩을 하고 제대로 표시되지 않는 경우 


1. Version 이 1.0.0 이 아닐 때 무한 로딩 발생하므로 버전을 1.0.0 이상으로 부여 (참고: github issue)

{
    "name": "my  API Server ",
    "version": "1.0.0",
    "description": "my Server api doc",
    "title": "Custom apiDoc browser title",
    "url" : "http://myserver.com/api/v1"
}


2. URL 맨 뒤에 / 를 추가해 볼 것


같이 보기

Ref