| Table of Contents |
|---|
apidoc는 는 nodejs 로 만든 API 문서화 프로그램으로 소스 코드내에 정해진 포맷에 맞게 기술하면 API 문서로 만들어 줍니다.
...
무겁고 사용이 불편한 swagger 에 비해서 설정과 사용이 쉽고 괜찮은 결과가 나와서 애용하고 있습니다.
기본 사용
npm global로 apidoc 을 설치합니다.
...
예로 저는 laravel 을 사용하므로 메인 소스가 있는 app 폴더에 아래와 같은 하이 폴더를 만들어 줍니다.
| Code Block | ||
|---|---|---|
| ||
mkdir -p app/Api/v1 |
API 를 문서화할 파일(예: app/Api/v1/AwesomeApi.php) 를 만들어서 다음 내용을 넣어줍니다.
| Code Block | ||
|---|---|---|
| ||
<?php
/**
* @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 옵션으로 지정합니다.
...
이제 public/apidoc 이라는 폴더에 static html 파일이 생성되었으므로 웹 서버를 띄우고 브라우저로 접속하면 됩니다.
확장자 지정
특정 확장자를 가진 파일만 문서화할 경우 -f 로 파일의 확장자를 정규식으로 지정해 줍니다.
...
| Code Block | ||
|---|---|---|
| ||
apidoc -i app/ -f ".*\.php$" -o public/apidoc |
템플릿 사용
템플릿을 별도로 사용하려면 -t 옵션으로 템플릿을 지정할 수 있습니다.
| Code Block | ||
|---|---|---|
| ||
apidoc -i app/ -f ".*\.php$" -o public/apidoc \ -t mytemplate/ |
제외 파일 지정
-e 옵션으로 제외할 파일을 지정할 수 있습니다.
...
| Code Block | ||
|---|---|---|
| ||
apidoc -i app/ -f ".*\.php$" -o public/apidoc \ -t mytemplate/ \ -e AdminController.php \ -e ResetPasswordController.php |
script 사용
매번 동일 명령어를 입력하지 말고 스크립트로 만들어 놓으면 편하게 사용할 수 있습니다.
...
| Code Block | ||
|---|---|---|
| ||
#!/usr/bin/env bash
apidoc -i app/ -f ".*\\.php$" -o public/apidoc \
-e AdminController.php \
-e ResetPasswordController.php
if [ $? -eq 0 ]; then
php artisan serve --port 9999
fi |
문서화
상세 사용법은 APIDoc 으로 REST API 문서화 하기 #2 참고하세요.
Trouble Shooting
Nothing to do
아래 메시지가 나오고 api 문서가 생성되지 않는 경우 apidoc tag 로 문서화가 안 되어 있어서 발생하므로 apidoc 형식에 맞게 문서화합니다.
| Code Block | ||
|---|---|---|
| ||
$ apidoc -i app/ -f ".*\.php$" -o public/apidoc
{"message":"Nothing to do.","level":"info"} |
무한 로딩
Apidoc 으로 생성한 문서 사이트가 무한 로딩을 하고 제대로 표시되지 않는 경우
...
| Code Block |
|---|
{
"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 맨 뒤에 / 를 추가해 볼 것