문서화 도구 Swagger vs Spring REST Docs

앞으로 팀 프로젝트에서 필요할 사전 지식을 전날 준비하기로 다짐했다.

노션에 틈틈이 기록해두는 것에 그치지 않고, 부족하지만 블로그에 정제된 문장으로 기록하는 연습을 해보겠다!

---

Swagger

OAS를 기반으로 구축된 오픈소스 도구 세트로, REST API를 설계, 빌드, 문서화하고 사용하는 데 도움이 된다.

 

* OAS: Open API Specification(이전 Swagger Specification), Rest API에 대한 API 설명 형식

 

일단 적용해보기

확실히 Spring REST Docs 문서를 생성해본 후 Swagger를 적용해보니, 신세계였다.

 

[TroubleShooting 1]

 

Swagger UI를 제공하는 라이브러리를 선택할 때 많은 레퍼런스에서 springfox를 사용하여, 나도 같은 라이브러리를 사용했다.

하지만 springfox는 현재 업데이트가 중단되어 Spring Boot 3에서부터 지원하지 않는다.

 

나의 경우 Spring Boot 3를 사용하므로 springfox가 아닌 아래와 같이 springdoc-openapi 라이브러리를 사용해야했다.

Springdoc-openapi는 springfox의 기능 외 추가 기능까지 제공하며 꾸준히 업데이트되고 있다고 한다.

implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.2.0'

 

직접 느낀 장단점

1. 자동 문서화의 장점

- 휴먼에러 방지

- 문서화 시간 단축

 

2-1. Swagger의 장점

- 클라이언트에게 친숙한 UI

- API 테스트 화면 제공

- 쉬운 문서화 (대부분 자동 생성)

 

2-2. Swagger의 단점

- 비즈니스 코드 침범

- 비즈니스 코드의 무결함과 무관하게 동작

 

---

Spring REST Docs

Spring에서 제공하는 문서화 도구로, 테스트 코드를 기반으로 API를 문서화한다.

테스트 코드를 기반으로 자동 생성된 snippet과 asciidoctor로 작성한 수작업 문서를 결합한다. = 원하는 정보를 쉽게 커스텀할 수 있다.

 

일단 적용해보기

이전 우아한테크코스 미션에서 진행한 경험이 있어 크게 어렵지 않았다.

 

직접 느낀 장단점

1-1. Spring Rest Docs의 장점

- 테스트 작성 및 성공을 강제함 (코드의 무결성 보장)

- API 실행 결과와 문서의 일치 여부 검증

- 커스텀 가능 범위가 넓음

- 비즈니스 코드 침범 X

 

1-2. Spring Rest Docs의 단점

- 디자인

- 적용 시 높은 시간 비용

 

---

 

이러한 Swagger와 Spring Rest Docs의 장단점을 서로 보완하기 위해 우리 팀은 두 도구를 모두 사용하기로 하였다.

적용해보고 후기 들고 와야지.

 

참고자료

 

에러 해결 관련

https://stackoverflow.com/questions/74614369/how-to-run-swagger-3-on-spring-boot-3

https://velog.io/@najiexx/Spring-Boot-3%EC%97%90-Swagger-%EC%A0%81%EC%9A%A9%ED%95%98%EA%B8%B0springdoc-openapi

 

Swagger 관련

https://www.baeldung.com/spring-rest-openapi-documentation

https://springdoc.org/#migrating-from-springfox

 

Spring REST Docs 관련

https://docs.spring.io/spring-restdocs/docs/current/reference/htmlsingle/#introduction