Springboot API 문서 자동화

swagger vs rest docs

spring에서 api를 문서화 할 때 제일 많이 쓰는 라이브러리다.

 

먼저 swagger는 ui에서 직접 api를 테스트 해볼수도 있고 rest docs와 비교해서 ui가 이쁘다.

하지만 단점도 확실하다.

1. 어노테이션을 통해 명세를 하게 되는데 지속적으로 사용하게 된다면 명세를 위한 코드가 많이 붙게되어서 전체적으로 가독성이 떨어진다.
2. 테스트기반이 아니기에 100% 신뢰 할 수 없는 문서이다.
3. 오류케이스에 대해서는 문서화하기가 까다롭다.

 

반면에 rest docs를 사용하면 위 단점들을 커버할 수 있지만. swagger의 장점은 포기하게 된다.

1. 테스트 코드 기반으로 작성되어서 swagger대비 많은 신뢰성을 확보 할 수 있다.
2. 테스트 코드 기반이기때문에 비지니스로직의 가독성에 영향을 끼치지 않는다.
3. ui에서 테스트는 불가능하다.

 

각각의 장점과 단점이 명확한데 우리는 그럼 뭘 써야 할까.

다행히도 각각의 장점만 뽑아서 우리의 고민을 해결해줄 그런 라이브러리가 하나 있다.

GitHub - ePages-de/restdocs-api-spec: Adds API specification support to Spring REST Docs

spring rest docs 기반으로 만들어진 테스트코드를 json이나 yaml로 뽑아서 swagger-ui에 붙이는 방식처럼 보이는데 적용 케이스들을 보니 잘만하면 해당 프로젝트에 접근하여 그 해당 프로젝트 API 문서만 볼 수 있는게 아니라 하나의 공간에서 우리 회사 프로젝트 API 문서들을 통합으로 관리를 할 수 있을 것도 같다.

(ps. 프로젝트별 스페이스를 나누어서 볼 수 있는지는 아직 모르겠다.)

(ps. 다른 회사는 MSA별 API 문서를 모아서 볼 수 있도록 관리를 하고 있더라…)

 

참조.Swagger와 Spring Restdocs의 우아한 조합 (by OpenAPI Spec)

참조2.OpenApiSpec.을 이용한 더욱 효과적인 API 문서화