Spring Boot SpringDoc OpenAPI

TMT

SpringDoc OpenAPI (2.8.3)의 Auto-Configuration 동작 방식
springdoc-openapi-starter-webmvc-ui:2.8.3를 의존성에 추가하면 Spring Boot의 **자동 구성(Auto-Configuration)**이 다음과 같이 활성화됩니다.

1. 자동 구성되는 주요 컴포넌트

컴포넌트	설명
`OpenAPI` 빈	API 메타데이터 (제목, 설명, 버전 등)를 포함하는 객체.
`SwaggerUI`	`/swagger-ui.html` 엔드포인트로 접근 가능한 웹 인터페이스.
`GroupedOpenApi`	API 그룹화 설정 (선택적).
`SpringDocConfigProperties`	`application.yml`에서 설정한 속성과 바인딩.
`OpenAPI` 문서 생성기	컨트롤러의 `@Operation`, `@Parameter` 등을 분석해 OpenAPI 스펙 생성.

2. Auto-Configuration의 핵심 로직

SpringDocAutoConfiguration 클래스가 다음을 자동으로 구성합니다:
- Swagger UI 엔드포인트: /swagger-ui.html, /swagger-ui/**
- OpenAPI JSON 엔드포인트: /v3/api-docs, /v3/api-docs/**
- Spring MVC 통합: 컨트롤러의 @GetMapping, @PostMapping 등을 스캔하여 API 문서화.
- 기본 OpenAPI 객체: info.title, info.version 등의 기본값 설정.

3. 기본 동작 예시

(1) 기본 API 문서 접근 경로

Swagger UI: http://localhost:8080/swagger-ui.html
OpenAPI JSON: http://localhost:8080/v3/api-docs

(2) `application.yml`을 통한 커스텀 설정

springdoc:
  swagger-ui:
    path: /docs       # Swagger UI 경로 변경
    tags-sorter: alpha
  api-docs:
    path: /api-docs   # OpenAPI JSON 경로 변경
  default-produces-media-type: application/json

(3) `@OpenAPIDefinition` 애노테이션을 통한 메타데이터 설정

@Configuration
@OpenAPIDefinition(
  info = @Info(
    title = "My API",
    version = "1.0",
    description = "API Documentation"
  )
)
public class OpenApiConfig {}

4. 주의사항

Spring Security와의 통합:
Swagger UI 엔드포인트에 접근하려면 Security 설정에서 허용해야 합니다.

@Bean
SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
    http
        .authorizeHttpRequests(auth -> auth
            .requestMatchers("/swagger-ui/**", "/v3/api-docs/**").permitAll()
        );
    return http.build();
}

Spring Boot 3.x 호환성:
SpringDoc 2.x는 Spring Boot 3.x와 호환되지만, Jakarta EE 9+ (javax → jakarta 패키지 변경)를 사용하는지 확인해야 합니다.
커스텀 OpenAPI 빈 중복 방지:
@Bean으로 수동 정의한 OpenAPI 객체가 있으면 자동 구성된 빈을 덮어씁니다.
필요 시 @Primary 애노테이션을 사용하세요.

5. 문제 해결

Swagger UI가 보이지 않는 경우:
- 의존성 버전 확인 (springdoc-openapi-starter-webmvc-ui).
- @EnableWebMvc 사용 시 WebMvcConfigurer를 통해 리소스 핸들러 추가 필요.
API 문서가 생성되지 않는 경우:
- 컨트롤러에 @RestController가 누락되지 않았는지 확인.
- @Operation, @ApiResponse 등 Swagger 애노테이션 사용 여부 체크.

✅ 정리

의존성 추가 → 자동 구성 완료: 별도 설정 없이 /swagger-ui.html 접속 가능.
커스텀 설정: application.yml 또는 @OpenAPIDefinition으로 간편히 조정.
Spring Security: 엔드포인트 접근 권한 필수.