문서화 위치

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 일 경우 [ ] 안에 파라미터 적어줍니다.

POST API

실행 가능하게 만들기

같이 보기

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

Ref

apidoc/example.js at master · apidoc/apidoc (github.com)

Browser not supported