[Spring Boot] SpringDoc

SpringDoc은 Spring Boot 애플리케이션에서 RESTful API 문서를 자동으로 생성하기 위한 라이브러리임. Swagger/OpenAPI 3.0 사양을 기반으로 하며, 애플리케이션의 API를 시각화하거나 클라이언트에서 테스트할 수 있는 도구를 제공함.

SpringDoc의 주요 기능

 

1. OpenAPI 정의 생성

• Spring 애플리케이션의 컨트롤러와 메서드를 기반으로 OpenAPI 3.0 문서를 자동 생성함.

2. Swagger UI 통합

• 애플리케이션 실행 시 Swagger UI를 통해 브라우저에서 API 문서를 시각화하고 테스트할 수 있음.

3. 지원되는 스프링 기능

• @RestController, @Controller와 @RequestMapping을 기반으로 동작함.
• 다양한 매개변수(@PathVariable, @RequestParam, @RequestBody) 및 응답 모델을 지원함.
• 스프링 보안(Spring Security)과 통합 가능.

4. OpenAPI 확장 기능

• 기본 OpenAPI 3.0 사양을 확장하여 더 풍부한 문서를 작성할 수 있음. 예를 들어, @Operation, @Schema 등의 어노테이션을 사용하여 문서에 추가 설명을 달 수 있음.

5. 멀티 프로파일 지원

• 활성화된 Spring 프로파일에 따라 서로 다른 OpenAPI 정의를 제공할 수 있음.

---

설치 방법

SpringDoc을 사용하려면 springdoc-openapi-starter-webmvc-ui 의존성을 추가해야 함.

build.gradle 설정

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

기본 설정

SpringDoc은 기본적으로 API 문서를 http://localhost:8080/swagger-ui.html에서 확인할 수 있도록 설정됨.

Swagger UI URL:

• 기본 주소: /swagger-ui.html
• OpenAPI JSON URL: /v3/api-docs

주요 어노테이션

SpringDoc은 Swagger/OpenAPI의 어노테이션을 지원하여 문서의 세부적인 정의를 가능하게 함.

 

1. @Operation

API 메서드의 설명, 요청, 응답, 태그 등을 정의할 때 사용.

@Operation(summary = "사용자 조회", description = "ID로 사용자 정보를 조회합니다.")
@GetMapping("/users/{id}")
public User getUserById(@PathVariable Long id) {
    return userService.findById(id);
}

 

2. @Schema

데이터 모델의 구조와 설명을 정의할 때 사용.

@Schema(description = "사용자 정보")
public class User {
    @Schema(description = "사용자 ID")
    private Long id;

    @Schema(description = "사용자 이름")
    private String name;

    // getters and setters
}

 

3. @Parameter

메서드 매개변수에 대한 추가 정보를 제공.

@GetMapping("/users")
public List<User> getUsers(
    @Parameter(description = "페이지 번호") @RequestParam int page,
    @Parameter(description = "페이지 크기") @RequestParam int size
) {
    return userService.findAll(page, size);
}

 

4. @ApiResponses 및 @ApiResponse

API 응답의 상태 코드와 설명을 문서화.

@ApiResponses(value = {
    @ApiResponse(responseCode = "200", description = "성공적으로 처리됨"),
    @ApiResponse(responseCode = "404", description = "사용자를 찾을 수 없음")
})
@GetMapping("/users/{id}")
public User getUserById(@PathVariable Long id) {
    return userService.findById(id);
}

---

고급 설정

1. 커스텀 OpenAPI 구성

@Bean을 사용하여 OpenAPI 객체를 커스터마이징할 수 있음.

@Bean
public OpenAPI customOpenAPI() {
    return new OpenAPI()
        .info(new Info()
            .title("사용자 API")
            .version("v1.0")
            .description("사용자 관리 API"));
}

 

2. Spring Security와 통합

Spring Security와 함께 사용하는 경우, Swagger UI와 API 문서가 인증되지 않은 사용자에게 접근 불가능할 수 있음. 이를 해결하려면 다음과 같이 Security 설정을 추가하면 됨.

@Override
protected void configure(HttpSecurity http) throws Exception {
    http.authorizeRequests()
        .antMatchers("/v3/api-docs/**", "/swagger-ui/**").permitAll()
        .anyRequest().authenticated();
}

---

 

장점

• Spring Boot와의 자연스러운 통합.
• OpenAPI 표준을 기반으로 하여 클라이언트 생성 및 도구 지원이 용이함.
• 간단한 의존성 추가만으로 설정 및 문서화 가능.

요약

SpringDoc은 Spring Boot 애플리케이션의 RESTful API를 Swagger UI를 통해 문서화하고 테스트할 수 있도록 돕는 강력한 도구임. 기본 설정만으로도 강력한 API 문서를 생성할 수 있으며, 다양한 어노테이션과 설정을 통해 세부적인 커스터마이징도 가능함.

 

 

 

 

출처 : ChatGPT