문서화 라이브러리 도입기

테스트 기반이 아닌, 어노테이션 기반 문서화 라이브러리를 선택한 이유

선요약

문서의 정확성이 유지되는 한에서 가장 사용 비용(노동력)이 적은 방법을 선택할 것이다.

기존 경험

지난 프로젝트에서 Rest Docs를 사용해본 결과 문서화에 에너지가 너무 많이 소모되었다.

특히 문서화를 위한 반복 작업, '노동'이 가장 컸다.

개선 시도, 재사용성 낮음

이 점을 개선하기 위해 추가적인 API를 작성했다.

enum + PayloadDocumentation.fieldWithPath 을 활용했다.

nested가 가능해 반복 작업을 줄이는 데는 큰 도움이 되었다.

하지만 이걸 팀 컨벤션으로 만드는 것도 어려울 것이라고 생각이 들었으며, 오히려 추후에 유지보수 비용이 커질 것이라고 생각했다.

그래서 협업 환경에서 사용하기엔 어려웠다.

다른 문서화 방식에 대한 오해

또, 당시에 Rest Docs를 사용해야겠다고 생각한 장점들이 꼭 그렇지만도 않다는 것을 알게 되었다.

당시 동작을 테스트한 API만 문서화된다는 점으로 인해 다음과 같은 장점이 있다고 생각했다:

• 문서화를 빠뜨릴 확률이 적다.
• 항상 프로덕션 코드에 맞춰 최신으로 유지된다. (최신이 아니면 테스트가 실패한다)

하지만 이것은 Rest Docs만의 장점은 아니었다.

• Rest Docs를 사용해도 문서화를 빠뜨릴 수 있다. (문서화는 선택사항이다)
• 오히려 이 측면에서는 어노테이션 기반 라이브러리가 코드와 상호작용하므로 별다른 추가 코드 없이 문서화된다는 장점이 있다.
• 어노테이션 기반 문서화 라이브러리도 사용자 코드와 상호작용하므로, 별다른 수정 없이 최신 상태로 유지된다.
• 프로덕션에 코드에 밀접한 측은 오히려 이쪽이 아닐까?

두 문서화 방식의 차이

둘의 차이는 최신화나 누락보다는 '테스트의 강제성'이었다.

Rest Docs를 사용한다면, 문서화를 위해 테스트를 꼭 작성해야 한다.

하지만 어차피 테스트를 작성한다면, 문서화를 꼭 테스트로 강제해야 할까?

특히 '노동'이 존재한다면, 그 시간을 더 가치있게 사용하는 편이 낫다고 생각했다.

그래서 Rest Docs대신 어노테이션 라이브러리를 선택했다.

어노테이션 기반 문서화 라이브러리를 사용하면

프로덕션 코드에 어플리케이션의 동작과 관련없는 문서화 관련 어노테이션이나 설정이 추가된다.

하지만 Rest Docs를 사용할 때의 지속적인 노동을 생각하면 이 편이 훨씬 효율적이지 않을까?

springfox vs springdoc

둘 다 어노테이션 기반, 프로덕션 코드에 추가된다는 점은 같다.

springfox는 최근 업데이트가 없어 버려진 라이브러리 취급을 받는 것 같다. 그래서 나중을 생각해 springdoc을 선택했다.

(아래에서 해결했다)

인증 문서화의 자동화

• 기존

핸들러(컨트롤러) 메서드에 다음과 같은 어노테이션을 붙여야 인증 문서화가 가능했다.

국내, 해외 통틀어 관련 자료가 아예 없다.

• 현재

컨트롤러에 문서화 어노테이션 추가 없이