SpringDoc

SpringDoc란?

SpringDoc는 Spring Boot 애플리케이션에서 OpenAPI 3.0 사양을 기반으로 REST API 문서를 생성할 수 있도록 도와주는 라이브러리입니다.
Swagger의 대안으로 Spring Boot와의 통합이 간편하며, API 문서를 자동으로 생성하는 기능을 제공합니다.

SpringDoc은 Swagger UI와 연동하여 브라우저에서 API 문서를 시각화하고 테스트할 수 있도록 지원합니다.

---

SpringDoc의 주요 특징

1. 간단한 설정

   • Spring Boot 환경에서 최소한의 설정으로 OpenAPI 문서를 자동 생성.

2. OpenAPI 3.0 지원

   • 최신 OpenAPI 3.0 사양과 완벽하게 호환.

3. Swagger UI 연동

   • Swagger UI를 통해 REST API 문서를 시각적으로 제공.

4. Spring Boot 기본 구성과 통합

   • Spring MVC, WebFlux, Spring Security와 원활히 작동.

5. 확장 가능성

   • 사용자 정의 API 문서를 쉽게 추가하거나 수정할 수 있는 기능 제공.

---

SpringDoc 사용법

1. SpringDoc 의존성 추가

Spring Boot 프로젝트에 Maven 또는 Gradle로 SpringDoc 의존성을 추가합니다.

• Maven

  <dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-ui</artifactId>
      <version>1.7.0</version>
  </dependency>

• Gradle

  implementation 'org.springdoc:springdoc-openapi-ui'

---

2. 간단한 API 예제 작성

Spring Boot REST API를 작성하면, SpringDoc이 이를 자동으로 문서화합니다.

• Controller 예제

  import org.springframework.web.bind.annotation.*;
  
  @RestController
  @RequestMapping("/api")
  public class UserController {
  
      @GetMapping("/users")
      public List<String> getAllUsers() {
          return List.of("Alice", "Bob", "Charlie");
      }
  
      @PostMapping("/users")
      public String createUser(@RequestBody String name) {
          return "User created: " + name;
      }
  }

---

3. Swagger UI 실행

Spring Boot 애플리케이션을 실행한 후, Swagger UI를 아래 경로에서 확인할 수 있습니다.

• Swagger UI 기본 경로: http://localhost:8080/swagger-ui.html
• OpenAPI 문서 경로: http://localhost:8080/v3/api-docs

Swagger UI에서 자동으로 생성된 API 문서를 확인하고, 테스트할 수 있습니다.

---

SpringDoc 주요 어노테이션

SpringDoc은 OpenAPI 문서를 세부적으로 조정하기 위해 다양한 어노테이션을 제공합니다. 아래는 자주 사용하는 어노테이션입니다.

1. @Operation

   • API 메소드의 설명, 요청/응답 정보 등을 정의.

   @Operation(summary = "모든 사용자 조회", description = "등록된 모든 사용자를 조회합니다.")
   @GetMapping("/users")
   public List<String> getAllUsers() {
       return List.of("Alice", "Bob", "Charlie");
   }

2. @Parameter

   • 메소드의 파라미터에 대한 설명 추가.

   @Operation(summary = "특정 사용자 조회")
   @GetMapping("/users/{id}")
   public String getUserById(
           @Parameter(description = "사용자 ID") @PathVariable int id) {
       return "User " + id;
   }

3. @Schema

   • 데이터 모델(객체) 정의를 상세히 기술.

   @Schema(description = "사용자 데이터")
   public class User {
       @Schema(description = "사용자 이름", example = "Alice")
       private String name;
   
       @Schema(description = "사용자 나이", example = "25")
       private int age;
   }

4. @ApiResponses

   • 메소드 응답에 대한 설명 추가.

   @Operation(summary = "사용자 생성")
   @ApiResponses(value = {
           @ApiResponse(responseCode = "200", description = "사용자 생성 성공"),
           @ApiResponse(responseCode = "400", description = "잘못된 요청")
   })
   @PostMapping("/users")
   public String createUser(@RequestBody String name) {
       return "User created: " + name;
   }

---

SpringDoc와 Swagger의 차이점

특징	SpringDoc	Springfox (Swagger)
기반 사양	OpenAPI 3.0	Swagger 2.0
설치 및 설정	간단하며 Spring Boot와 자연스럽게 통합	더 복잡하고 추가적인 설정이 필요
지원	Spring Boot 2.x 이상	Spring Boot와의 호환성 제한
기능 업데이트	OpenAPI 최신 사양 지원	Swagger 사양에 종속

---

SpringDoc의 장점

1. 최신 사양 지원
   OpenAPI 3.0을 기본으로 사용하여 최신 API 문서화 요구사항 충족.

2. Spring Boot와의 통합
   Spring Boot 애플리케이션에서 기본 구성으로 쉽게 설정 가능.

3. 사용자 친화적
   Swagger UI를 통해 쉽게 API를 시각화하고 테스트.

4. 적은 의존성
   추가 설정 없이 기본적으로 필요한 기능 대부분 제공.

---

SpringDoc의 한계

1. 비표준 환경 지원 제한
   Spring Boot 외의 프레임워크에서는 사용이 제한적.

2. 복잡한 문서화 작업 시 추가 설정 필요
   대규모 프로젝트에서는 OpenAPI 문서 작성 및 유지 보수가 복잡해질 수 있음.

---

SpringDoc를 사용하는 이유

SpringDoc은 간단한 설정과 강력한 OpenAPI 지원 덕분에 REST API 문서를 생성하는 가장 효율적인 방법 중 하나입니다. 특히 Spring Boot 애플리케이션과의 높은 호환성으로 인해 현대적인 API 개발에서 널리 사용됩니다.

추가 학습 자료

• [Spring Boot] Springdoc 라이브러리를 통한 Swagger 적용
• springdoc-openapi v2.8.1