APIDoc 으로 REST API 문서화 하기 #2
- 정광섭
Owned by 정광섭
문서화 위치
apidoc 이나 기타 도구로 문서화를 할 때 드는 고민은 실제 소스 코드내에 주석으로 작성할 지 아니면 별도의 파일에 작성할 지 여부입니다.
정답은 없고 취향과 사용 도구에 따라 달라지겠지만 개인적으로는 프로젝트를 문서화할 때 소스와 별도로 API 문서화 파일에 작성하는 것으로 정했고 이유는 다음과 같습니다.
- apidoc 는 언어의 Annotation 기능을 활용해 method signature에 맞게 자동으로 API 문서를 생성해 주지 않습니다.
그래서 굳이 한 파일에 작성할 이점이 없습니다. - 주석 방식으로 사용하다 보니 설명이 꽤 길어지는데 긴 주석때문에 정작 소스 코드를 이해하고 작성하기 더 불편해 집니다.
소스 코드와 API 문서가 달라지면 어떻게 하냐고요?
그건 소스 코드에 직접 API 문서를 작성해도 발생할 일이며 소스 코드 리뷰등 내부 개발 문화 개선을 통해서 해결해야 한다고 생각합니다.
header/Footer 사용
API 문서에 공통으로 들어가는 헤더와 푸터를 사용하려면 apidoc.json 에 header 와 footer 항목을 추가하고 markdown 파일을 만들어 주면 됩니다.
{
"name": "my project",
"version": "1.0.0",
"description": "my project apiDoc basic example",
"title": "Custom apiDoc browser title",
"url": "https://myproject.example.com/v1",
"header": {
"title": "My own header title",
"filename": "header.md"
},
"footer": {
"title": "My own footer title",
"filename": "footer.md"
}
}
header.md 와 footer.md 파일을 만들어 줍니다.
# header.md apidoc 헤더 파일입니다. ```bash git clone https://github.com/apidoc/apidoc && cd apidoc npm install --prod ./bin/apidoc -i example -o /tmp/doc $BROWSER /tmp/doc ```
# footer 파일 apidoc 에 추가할 footer 내용입니다. ```bash ls -l ```
이제 apidoc 으로 매뉴얼을 컴파일하고 browser 로 접속하면 헤더와 푸터를 볼 수 있습니다.
API 예제
/**
* @api {post} /users/create 사용자 등록
*
* @apiDescription 새로운 사용자 정보를 등록합니다.
*
* @apiVersion 1.0.0
* @apiName product-create
* @apiGroup products
*
* @apiParam {String} name 이름
* @apiParam {String} address 주소
* @apiParam {String} [address_detail] 상세 주소
* @apiParam {Number} post_num 우편 번호
*
* @apiSampleRequest /api/v1/users/create
*
* @apiHeader {String} Authorization='Bearer KYVAFULuO7fDHjZ3oiCLgYGdTclmkGKLyiakSFqg'
*
* @apiExample {curl} Example usage:
* curl --header "Content-Type: application/json"\
* --header "Authorization: Bearer 1|KYVAFULuO7fDHjZ3oiCLgYGdTclmkGKLyiakSFqg" \
* --request POST \
* --data '{"name":"홍길동", "address": "제주도", "address_detail: "성산읍", post_num: 12345 }' \
* http://api.example.com/api/v1/users/create
*
* @apiParamExample {dn} Request-Example:
* {
* "name": "홍길동", "address": "제주도"
* }
*
* @apiSuccess {String} result ok
*
* @apiSuccessExample Success-Response:
* HTTP/1.1 200 OK
* {
* "result": true
* }
*
* @apiError {String} message 결과 메시지
* @apiError {String[]} errors 상세 에러 메시지
*
* @apiErrorExample 422 IP 허용 안 됨
* HTTP/1.1 422 Unprocessable Entity
* {
* "data": {
* "message": "Unprocessable Entity",
* "errors" : [
* "이름은 필수 필드입니다."
* ]
* }
* }
*
* @apiErrorExample 422 파라미터 에러
* HTTP/1.1 422 Unprocessable Entity
* {
* "data": {
* "message": "Unprocessable Entity",
* "errors" : [
* "우편번호 형식이 아닙니다."
* ]
* }
* }
*/
apiParam
optional 일 경우 [ ] 안에 파라미터 적어줍니다.