오늘은 REST api를 문서화하는 툴인 apidoc 사용법에 대한 글을 작성하고자 한다.
필자의 팀 내에서 api 문서는 Swagger 툴을 활용해서 문서화를 했었다.
그마저도 swagger를 사용하기보다는, 알아서 코드보고 파악하거나 해당 api개발자에게 간단한 명세를 요청하는 정도로 해결했었지만,
타사와의 협업할 기회가 생겨, api 명세서를 전달할 일이 생겼다. 깔끔하게 api 문서화를 해야했고, 팀의 판단으로는 Swagger 보다는 apidoc이 깔끔하고 한 눈에 들어온다고 생각했다. 결론적으로 apidoc 툴을 사용해서 명세서를 다시 작성하기로 결정했다.
초반에 Swagger를 선택했던 이유는, 팀 내에서만 api를 사용했기때문에, 운영에 리소스를 많이 들이지 않는 것이 목표였기 때문이다.
초반 구축 난이도는 apidoc보다 높은 편이라고 하지만, 이후에는 코드 몇 줄을 추가하는 수준으로 자동으로 문서화를 해주기 때문에 매우 편리했다. 또한 request-response 를 즉시 테스트할 수 있다는 장점이 있다.
하지만 현재는 외부에 공개할 규격서를 작성하기 위한 것이므로, api프로젝트와 api 규격서를 따로 운영 가능한 apidoc이 더 적절하다고 판단했다. 그러나..... 단점으로는 노가다 수동으로 직접 다 써줘야한다는 점을 꼽을 수 있다. 치명적이다^^;;
시작 (설치)
npm install apidoc
apidoc -v
_ _
__ _ _ __ (_) __| | ___ ___
/ _' | '_ \| |/ _' |/ _ \ / __|
| (_| | |_) | | (_| | (_) | (__
\__,_| .__/|_|\__,_|\___/ \___|
|_| v1.0.3설치가 잘 되었는 지 확인하자.
apidoc.json 만들기
: 프로젝트 루트 폴더에 apidoc.json 생성
- 프로젝트 루트 폴더
ㄴ src/
ㄴ apidoc.json{
"name": "my api",
"version": "1.0.0",
"description": "api에 대한 설명",
"title": "apiDoc 제목",
"url" : "http://example.com/api/v1"
}- name: 프로젝트 이름
- version: 프로젝트 버전
- description: 소개, 설명
- title: 브라우저 제목
- url: api 경로
api 규격서 작성
/**
* @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.
*
* @apiSuccessExample Success-Response:
* HTTP/1.1 200 OK
* {
* "firstname": "John",
* "lastname": "Doe"
* }
*
* @apiError UserNotFound The id of the User was not found.
*
* @apiErrorExample Error-Response:
* HTTP/1.1 404 Not Found
* {
* "error": "UserNotFound"
* }
*/해당 js파일은 프로젝트 루트/src/ 아래에 두면 된다.
apidoc -i src -o apidoc명세서를 다 작성했으면, 파일을 생성해보자.
src/doc/index.html 파일이 생성된다. 해당 파일을 열어보면, 생성된 명세서를 확인할 수 있다.
Params 작성법
@api
@api {method} path title필수 param로 가장 윗부분에 작성한다. 어떤 method API인지 알려주는 param이다.
method는 get, post, delete, update 등을, path에는 api url 이후에 작성하는 경로를, title에는 간단한 설명을 작성하면 된다.
@apiBody
@apiBody [{type}] [field=defaultValue] [description]request body로 요청받는 필드들을 작성하는 param이다.
- type: 파라미터 타입(Boolean, Number, String 등)
- field: 파라미터명
- description: 파라미터 설명
@apiParam
@apiParam [(group)] [{type}] [field=defaultValue] [description]@apiParam은 api path 뒤에 파라미터로 붙이는 부분을 작성해주는 param이다. 필자는 주로 update method에서 id를 찾아서 수정해줄 때, id를 파라미터로 사용한다.
- type: 파라미터 타입(Boolean, Number, String 등)
- field: 파라미터명
- description: 파라미터 설명
@apiSuccess
@apiSuccess [(group)] [{type}] field [description]- type: 파라미터 타입(Boolean, Number, String 등)
- field: 파라미터명
- description: 파라미터 설명
예시)
/**
* @api {get} /users
* @apiSuccess {Object[]} profiles List of user profiles.
* @apiSuccess {Number} profiles.age Users age.
* @apiSuccess {String} profiles.image Avatar-Image.
*/
api 요청에 성공적으로 응답할때, response에 수신해주는 결과 파라미터 정보이다.
@apiSuccessExample
@apiSuccessExample {json} Success-Response:
{ "content": "This is an example content" }예시)
/**
* @api {get} /user/:id
* @apiSuccessExample {json} Success-Response:
* HTTP/1.1 200 OK
* {
* "firstname": "John",
* "lastname": "Doe"
* }
*/api 요청에 성공적으로 응답할때, 리턴해주는 메세지/데이터를 작성해준다.
이외에도 apiError, apiQuery 등을 작성해줄 수 있다. 더 필요한 정보는 https://apidocjs.com 에서 찾아서 사용하면된다.
