Springdoc-Openapi

• Spirng Boot 애플리케이션을 OpenAPI3(이전의 Swagger) 와 통합하는 라이브러리
• Spring Boot 컨트롤러 및 엔드포인트를 기반으로 API에 대한 문서를 자동으로 생성한다.

최소 요구 사항

• spring-boot v3 이상 : springdoc-openapi v2
• spring-boot 2.x 및 1.x : spirngdoc-openapi v1.7.0

장점

• 간단하고 사용이 쉬움
• 다양한 도구 및 플랫폼과 광범위하게 지원되고 호환
• Swagger를 기본 지원 하므로 문서가 보기에 예쁘다.
• API를 테스트 해볼 수 있다.
• TDD 서비스가 아니어도 사용할 수 있다.
• 의존성만 추가해도 기본 UI를 제공한다.

단점

• 복잡한 시나리오를 문서화하거나 출력 형식을 사용자 정의하는 측면에서 Spring RestDocs만큼 유연하지 않을 수 있다.
• 프로덕션 코드에 문서화와 관련된 코드가 추가되어 가독성 및 객체지향 관점에서 별로다.
• 테스트 기반이 아니라서 문서의 신뢰도가 떨어진다.
• 지원하는게 많다보니? 무겁다. ( openAPI, springBoot, Swagger-ui, OAuth2, ... )
• 많은 어노테이션의 향연
• Spring Framework Contributors(Pivotal)가 유지 관리하지 않는 커뮤니티 기반 프로젝트
• API 가 변경되더라도 어노테이션을 변경하지 않으면 API 문서는 수정되지 않는다.

Spring Rest Docs

• Spring Boot 애플리케이션에서 RESTful API에 대한 정확한 문서를 작성하기 위해 Spring 커뮤니티에서 개발한 프레임워크
• 테스트 기반 접근 방식을 취하며 문서는 Spring MVC 테스트, Spring Webflux의  WebTestClient 또는 REST-Assured로 작성됩니다.
• 직접 작성한 문서와 Spring MVC Test 또는 WebTestClient로 생성된 자동 생성된 스니펫을 결합하여 RESTful 서비스를 문서화

최소 요구 사항

• java17
• 스프링 프레임 워크 6

장점

• 생성된 문서를 상세하고 세밀하게 제어할 수 있으므로 복잡한 API 또는 특정 문서 요구 사항이 있는 프로젝트에 적합
• 사용자 친화적이고 설명이 풍부한 문서를 작성할 수 있는 도구를 제공하여 개발자와 테크니컬 작가 간의 협업을 가능하게함
• 프로덕션 코드에 영향을 주지 않는다.
• 테스트 기반으로 생성되어 신뢰도가 높다.

단점

• 높은 러닝커브
• 문서 스니펫을 작성하려면 수동 작업이 필요하며 springdoc-openapi에 비해 더 많은 초기 설정이 필요
• 엔드포인트에 따라 설정해야할 코드가 많아진다.
• 테스트의 결과로 생성된 스니펫은 Asciidoctor를 사용한다. (example.adoc)

정리

API 문서화의 목적은 API 스펙을 정의하는 것이다.

내 입장에서는 Springdoc-Openapi는 좀더 API 스펙의 정의의 중요성을 줄이고 테스팅, 및 다른 부분에 투자를 한 느낌이고
Spring Rest Docs는 API 스펙에만 집중을 한 느낌이다.

규모가 작거나 간단한 프로젝트면 Springdoc-Openapi 가 더 적합? 할것같고 규모가 크거나 복잡한 프로젝트에는 Spring Rest Docs가 더 적합해 보인다.

Reference

https://docs.spring.io/spring-restdocs/docs/current/reference/htmlsingle/#getting-started
https://github.com/springdoc/springdoc-openapi