Api 문서화 도구 REST Docs vs Swagger

[Libienz]

api 문서화 도구로 REST Docs가 좋은가 Swagger가 좋은가 🤔

[mzeong]

선정 이유

레벨 2 때는 크루들이 주로 REST Docs를 선택했으나, 프로젝트에서는 다수가 Swagger를 선택함 > 의문

대표 진영의 논리 (장/단점)

• REST Docs: 신뢰성, 테스트 강제, controller 코드 오염 x / 러닝커브 높음, 테스트 강제가 단점이 될 수도 있음
• Swagger: 테스트 x, 가벼움, 러닝커브 낮고 빠르게 적용 가능 / 프로덕션 코드 오염 & 의존성 생김, 문서 신뢰도 낮음

의견

REST Docs - 리비
Swagger - 콜리, 제리, 에버

토론

[Swagger] 테스트 목적이 희석됨, 문서화를 위한 테스트 코드를 작성하게 됨, 유연하지 않다고 느껴짐

[Swagger] 어노테이션 붙이는 것이 테스트 작성하는 것보다 간편

[Swagger] API 문서는 속도가 생명, 느리게 완벽한 문서를 주는 것은 의미가 없다고 생각

[REST Docs] curl 제공하므로 web testing과 유사한 기능을 누릴 수 있음

[REST Docs] 신뢰성이 제일 중요
ㄴ 반박: Schema 반환형 지정할 수 있음(변경 포인트 줄일 수 있음), 문자열 의존성은 REST Docs도 마찬가지

[REST Docs] 의존성 제거 측면에서 좋음
ㄴ 반박: 외부 라이브러리 의존성과 관련해서는 REST Docs도 같이 앓고 있는 문제임
ㄴ 재반박: runtime dependency 없음이 제일 멋진 부분, Swagger는 runtime에 의존성 필요
ㄴ 재반박: 반박 불가, 그러나 큰 단점이라고 생각하지 않음, 과연 치명적일까?

[REST Docs] Swagger 쓰면 컨트롤러 코드 복잡해지지 않음?
ㄴ 반박: 문서 관련 코드 인터페이스로 분리해 프로덕션 침범 낮춤, 커스텀 어노테이션 사용으로 중복 코드 제거
ㄴ 재반박: 파일을 분리하는 것은 해결책이 아니라 생각, 휴먼에러 가능성 o

[Swagger] REST Docs가 관심사가 합쳐져 있고 Swagger가 관심사의 분리라 느껴짐 + 수정 시 수정 지점이 오히려 명확

[REST Docs] 안돌이 REST Docs contributor임

[그 외] REST Docs, Swagger를 둘 다 사용하여 장점만 취할 수 있음, REST Docs와 비슷한 수준의 공수