[배경]
- 문서따로 소스따로를 해결하고 싶었다.
- 매번 변경이 생길때마다 둘다를 손보는건 번거롭다.
- 구글은 REST Java 에 대해 소스로부터 문서 자동 생성으로 방향을 잡았다고 들었다.
[전제사항]
- Spring MVC 를 쓰고 있다. (혹은 annotation에 기반한 개발을 하고 있다.. )
- 대상 클래스들이 classpath에 포함되어 있어야 한다.
[처리흐름]
1. filter Controller class // 자바소스 중에서 Controller, RequestMapping Annotation을 가진 class들을 추출한다.
2. filter RequestMapping Method // 추출된 class들에서 RequestMapping Annotation을 가진 method들을 추출한다.
3. get return type // 추출된 method에서 return type을 가져온다.
// method.getGenericReturnType()
4. get request mapping method // 사용하고 있다면 mapping method 값도 가져온다. (cf. REST)
5. filter RequestParam arguments // method 의 RequestParam 으로 정의한 parameter 정보도 추출한다.
6. do pretty print // 예쁘게 출력한다.
[출력결과 샘플]
### XXXXX Specification Document
### Created Mon Jul 23 09:12:08 KST 2012 ###
============================
Resource : xxxxxxx
GET URI : <BASE_URL>/xxxxxxx/{xxxxxxid}
PAREMETERS : N/A
RETURN : Sample
RETURN DETAIL :
{
"Sample": [
"ID": "long",
"Name": "String"
]
}
[회고]
1. java, Spring이 제공하는 Annotation 만으로는 문서를 만드는데 필요한 충분한 정보가 부족하더라.
ex. description, 예외처리정보 등... => 개발초기에 custom annotation 을 고려해야겠더라.
2. 엑셀, 워드로 뽑아주려고 했더니 회사 문서보안시스템이 허용하지 않더라.
혹시 누군가 필요로 한다면 MS가 추가한 xml의 축복을 누리시길. ( http://www.docx4java.org )
3. 재미나는 작업이었지만 결국 실제적인 도움을 주지는 못했다. (자동생성하기에는 담을 수 있는 내용이 부족했다.) => 다음엔 좀더 가치있게 되도록 사전에 고려를..
4. 반대로 Spec 문서에서 Skeleton 코드를 생성할 수도 있지 않을까...
(가능은 하지만 당장은 One source, Multi use 를 하는게 더 정신건강에 이로울듯 싶다. )