Spring Boot 시리즈 24편 – Swagger와 SpringDoc을 활용한 API 문서 자동화 전략

Spring Boot에서 Swagger와 SpringDoc(OpenAPI 3)으로 API 문서를 자동화하는 방법을 설명합니다. 설정, 문서화 커스터마이징, 운영 환경 적용 팁까지 실전 중심으로 정리했습니다.

 

---

 

Spring Boot 시리즈 24편 – Swagger와 SpringDoc을 활용한 API 문서 자동화 전략

 

현대 개발에서 API 문서는 선택이 아니라 필수입니다.

내부 팀원, 프론트엔드, 외부 파트너, B2B 고객까지 모두가 정확하고 일관된 API 명세를 원합니다.

Spring Boot 프로젝트에서는 Swagger와 SpringDoc을 통해 이를 자동화할 수 있습니다.

 

이번 글에서는 Spring Boot 2.x/3.x 환경에서의 문서 자동화 도구 선택 기준,

SpringDoc(OpenAPI 3)의 설정과 커스터마이징 전략,

배포 환경 적용 팁까지 실전 중심으로 정리합니다.

 

---

 

📌 1. Swagger vs SpringDoc – 어떤 걸 써야 할까?

항목Swagger(SpringFox)SpringDoc(OpenAPI 3)

기본 지원	Spring Boot 2.x까지 최적화	Spring Boot 3.x 이상 표준
OpenAPI 호환	OpenAPI 2.0(Swagger 2.0)	OpenAPI 3.0 이상 완전 지원
유지관리	비활성화됨 (2022년 이후)	활발한 업데이트 중
Kotlin/Reactive 지원	낮음	우수
추천도	❌ (구버전 전용)	✅ (Spring Boot 3.x 기준 필수)

🔍 결론: Spring Boot 3 이상에서는 반드시 SpringDoc(OpenAPI 3) 사용 권장

 

---

 

✅ 2. SpringDoc(OpenAPI 3) 기본 적용

 

 

1️⃣ Gradle 의존성 추가

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

 

 

---

 

2️⃣ 기본 Swagger UI 주소

http://localhost:8080/swagger-ui.html

또는

http://localhost:8080/swagger-ui/index.html

 

 

---

 

3️⃣ 예제 컨트롤러

@RestController
@RequestMapping("/api/users")
public class UserController {

    @GetMapping("/{id}")
    public ResponseEntity<UserResponse> getUser(@PathVariable Long id) {
        return ResponseEntity.ok(new UserResponse(id, "홍길동", "user@example.com"));
    }
}

→ 별도 주석 없이도 자동으로 문서 생성

 

---

 

🛠️ 3. 문서 커스터마이징 (OpenAPI 설정)

 

 

1️⃣ 기본 정보 설정

@Configuration
@OpenAPIDefinition(
    info = @Info(
        title = "MyApp API",
        version = "v1",
        description = "Spring Boot 기반 REST API 명세서",
        contact = @Contact(name = "API팀", email = "api@myapp.com")
    )
)
public class OpenApiConfig {}

 

 

---

 

2️⃣ 파라미터/응답 주석 처리 (Swagger Annotations)

@Operation(summary = "사용자 정보 조회", description = "ID 기반 사용자 조회 API")
@ApiResponses({
    @ApiResponse(responseCode = "200", description = "조회 성공"),
    @ApiResponse(responseCode = "404", description = "사용자 없음")
})
@GetMapping("/{id}")
public ResponseEntity<UserResponse> getUser(@PathVariable Long id) {
    return ResponseEntity.ok(...);
}

 

 

---

 

🔐 4. 인증 헤더 추가 방법 (JWT 등)

@Bean
public OpenAPI customOpenAPI() {
    return new OpenAPI()
        .addSecurityItem(new SecurityRequirement().addList("BearerAuth"))
        .components(new Components()
            .addSecuritySchemes("BearerAuth", new SecurityScheme()
                .type(SecurityScheme.Type.HTTP)
                .scheme("bearer")
                .bearerFormat("JWT")));
}

→ Swagger UI 상단에 토큰 입력창 자동 생성됨

 

---

 

🌍 5. 운영 환경에서의 적용 전략

항목전략

외부 공개 여부	springdoc.swagger-ui.enabled=false 설정으로 운영 비공개
API Gateway 연동	리버스 프록시 설정 (Swagger 경로 허용)
문서 배포 자동화	CI에서 정적 문서로 변환해 S3/CloudFront 배포 가능 (springdoc-openapi-maven-plugin)
버전 관리	OpenAPIDefinition을 모듈별로 분리해 v1/v2 명시 가능

 

 

---

 

✅ 마무리 요약

항목요약

추천 도구	SpringDoc(OpenAPI 3) – Spring Boot 3 이상 호환
기본 UI 주소	/swagger-ui/index.html
문서 자동화	컨트롤러 + DTO 자동 추론, 주석으로 세부 설정 가능
보안 적용	JWT/BasicAuth 등 Swagger UI 내 테스트 지원
확장 전략	정적 문서화, API Gateway, 외부 파트너 연동 활용 가능

 

 

---

 

📌 다음 편 예고

 

Spring Boot 시리즈 25편: 멀티 프로파일 설정 전략 – dev/staging/prod 환경 분리 실전 가이드