문서화 위치

apidoc 이나 기타 도구로 문서화를 할 때 드는 고민은 실제 소스 코드내에 주석으로 작성할 지 아니면 별도의 파일에 작성할 지 여부입니다.

정답은 없고 취향과 사용 도구에 따라 달라지겠지만 개인적으로는 PHP 프로젝트에 문서화할 때 별도의 파일에 작성하는 것으로 정했고 이유는 다음과 같습니다.


  1. apidoc 는 언어의 Annotation 기능을 활용해 method signature에 맞게 자동으로 API 문서를 생성해 주지 않습니다.
    그래서 굳이 한 파일에 작성할 이점이 없습니다.
  2. 주석 방식으로 사용하다 보니 설명이 꽤 길어지는데 긴 주석때문에 정작 소스 코드를 이해하고 작성하기 더 불편해 집니다.


소스 코드와 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"
    }
}
JS


header.md와 footer.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
```
CODE
# footer 파일

apidoc 에 추가할 footer 내용입니다.

```bash
ls -l
```
CODE


이제 apidoc 으로 매뉴얼을 컴파일하고 browser 로 접속하면 헤더와 푸터를 볼 수 있습니다.


POST API



실행 가능하게 만들기


같이 보기


Ref