Spring Boot 3.x + Swagger(OpenAPI 3.1) 완벽 가이드 : 설정부터 보안까지

최소 사양 

• Java 버전 : 최소 JDK 17 이상 필요 (Spring Boot 3 기본 요구 사양)
• Jakarta EE : 기존 javax.* 패키지가 아닌 jakarta.* 패키지 기반의 코드로 작성
• Spring Security 접근 권한 허용
  
  📌 허용해야 할 주요 경로
  
  • /v3/api-docs/ : OpenAPI 명세서(JSON/YAML)가 생성되는 경로
  • /swagger-ui/ : Swagger UI 페이지 접속 경로
  • /swagger-ui.html : Swagger UI 메인 엔트리
  •  

 

 

Swagger 구축 전제 조건

 

1. Springdoc-openapi v2 사용해야하므로 Gradle 의존성에 버전 추가 및 변경

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

 

 

2. 보다 더 RESTful한 API를 만들기 위해서는 메타데이터를 설정하는 클래스 필요

@Configuration
public class OpenApiConfig {

    @Bean
    public OpenAPI springShopOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("내 프로젝트 API 명세서")
                        .description("Spring Boot 3 기반 기술 블로그 예제 API입니다.")
                        .version("v1.0.0")
                        .license(new License().name("Apache 2.0").url("http://springdoc.org")))
                .externalDocs(new ExternalDocumentation()
                        .description("프로젝트 위키/노션 가이드")
                        .url("https://example.com/docs"));
    }
}

 

 

3. Swagger Annotation OpenAPI 3 표준에 맞게 변경

구버전 (Springfox)	신버전 (Springdoc)	적용 위치
@Api	@Tag	Controller Class
@ApiOperation	@Operation	Controller Method
@ApiParam	@Parameter	Method Parameter
@ApiModelProperty	@Schema	DTO Field

 

① Controller level

 @Tag  : 컨트롤러가 어떤 기능을 담당하는지 그룹 이름을 작성

 

② Method level

 @Operation  : API가 구체적으로 무엇을 하는지 summary와 description을 작성

 @ApiResponses / @ApiResponse  : 이 API가 던질 수 있는 성공(200), 실패(400, 500) 케이스를 작성

 @Parameters / @Parameter  : @PathVariable이나 @RequestPㄱaram으로 받는 인자들에 대한 설명을 작성

 

③ Model level(DTO/Entity)

 @Schema  : 데이터 모델(DTO) 클래스나 그 안의 필드(변수)에 설명

 

예제 👉

@Tag(name = "Product", description = "상품 관련 API") // 1. 컨트롤러 레벨
@RestController
public class ProductController {

    @Operation(summary = "상품 등록", description = "관리자가 새로운 상품을 시스템에 등록합니다.") // 2. 메서드 레벨
    @PostMapping("/products")
    public ProductResponse createProduct(
        @Parameter(description = "등록할 상품 정보") @RequestBody ProductRequest request // 2. 파라미터 레벨
    ) {
        return new ProductResponse(1L, "MacBook", 2000000);
    }
}

@Schema(description = "상품 등록 요청 데이터") // 3. 모델 레벨
class ProductRequest {
    @Schema(description = "상품명", example = "MacBook Pro")
    private String name;
    
    @Schema(description = "가격", example = "3000000")
    private int price;
}

 

 

4. application.yml 설정

springdoc:
  swagger-ui:
    path: /api #기본 경로인 /swagger-ui.html 대신 사용

 

운영 환경에서의 보안 이슈가 발생하므로 이를 방지하기 위해서는 운영 환경에서는 설정을 아래 방식으로 설정

# application-prod.yml
springdoc:
  api-docs:
    enabled: false
  swagger-ui:
    enabled: false

 

 

5. 접속 확인

• Swagger UI : http://localhost:8080/api
• OpenAPI 명세(JSON) : http://localhost:8080/v3/api-docs