Spring Boot 시리즈 6편 – Swagger를 활용한 API 문서 자동화 전략

Spring Boot에서 Swagger(OpenAPI)를 활용해 REST API 문서를 자동으로 생성하는 방법을 설명합니다. 설정부터 커스터마이징, 실전 적용 전략까지 포함합니다.

---

Spring Boot 시리즈 6편 – Swagger를 활용한 API 문서 자동화 전략

API를 설계하고 구현하는 것만큼 중요한 것이 바로 문서화입니다.
특히 백엔드와 프론트엔드, 앱 개발자 간 협업에서는 정확하고 자동으로 관리되는 API 명세가 핵심이 됩니다.

이번 글에서는 Spring Boot에서 **Swagger(OpenAPI 3.0)**를 적용하여
API 문서를 자동 생성하고, 유지보수 비용을 줄이며, 실시간 테스트도 가능한 환경을 구축하는 방법을 소개합니다.

---

📌 1. Swagger란?

Swagger는 REST API 문서를 자동 생성해주는 툴입니다.
현재는 OpenAPI 스펙으로 발전했으며, Spring에서는 springdoc-openapi 라이브러리가 가장 많이 사용됩니다.

✅ 주요 기능

• API 명세 자동 생성
• UI 기반 테스트
• 명세서 자동 업데이트
• YAML/JSON 명세 파일 추출 가능

---

🔧 2. Spring Boot에서 Swagger 적용하기

1️⃣ Gradle 의존성 추가

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

최신 버전은 공식 문서에서 확인 가능

---

2️⃣ 기본 사용 방법

설정만으로 /swagger-ui/index.html 경로에 API 문서 UI가 생성됩니다.

• 경로: http://localhost:8080/swagger-ui/index.html
• 명세: http://localhost:8080/v3/api-docs

---

3️⃣ 컨트롤러 주석 작성

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

    @Operation(summary = "사용자 단건 조회", description = "사용자의 ID로 정보를 조회합니다.")
    @GetMapping("/{id}")
    public ResponseEntity<UserDto> getUser(@PathVariable Long id) {
        ...
    }
}

• @Operation은 API 설명
• @Parameter, @Schema, @ApiResponses 등으로 세부 문서화 가능

---

✅ 3. 커스터마이징 전략

1️⃣ 전역 API 정보 설정

@Configuration
public class OpenApiConfig {

    @Bean
    public OpenAPI apiInfo() {
        return new OpenAPI()
            .info(new Info()
                .title("MyApp API")
                .description("Spring Boot 기반 API 문서")
                .version("v1.0.0"));
    }
}

---

2️⃣ DTO에 필드 설명 추가

public class UserDto {

    @Schema(description = "사용자 이름", example = "홍길동")
    private String name;

    @Schema(description = "이메일 주소", example = "test@example.com")
    private String email;
}

• 프론트엔드 개발자에게 필수 정보 전달 가능

---

🧠 실무 적용 팁

항목 전략

보안 설정	운영 환경에서는 Swagger 경로를 보호 (예: 관리자 인증)
API 문서 내보내기	/v3/api-docs.yaml → 명세서 백업, 외부 공유
명세 테스트	Swagger UI를 통해 직접 Request/Response 테스트
커스텀 응답	@ApiResponse, @ApiResponses로 상세 HTTP 응답 명시
그룹화	group 설정으로 버전별 문서 분리 가능

---

🧪 예시: API 응답 문서화

@Operation(summary = "회원 가입", responses = {
    @ApiResponse(responseCode = "200", description = "회원가입 성공"),
    @ApiResponse(responseCode = "400", description = "입력값 오류"),
    @ApiResponse(responseCode = "409", description = "이메일 중복")
})
@PostMapping
public ResponseEntity<ApiResponse<Void>> register(@RequestBody RegisterUserRequest request) {
    ...
}

---

📦 Swagger 문서 자동화의 장점

항목 설명

협업 효율 ↑	프론트/앱 개발자와 실시간 공유 가능
유지보수 ↓	코드 기반 자동 반영으로 문서 누락 최소화
테스트 간편	직접 API 호출 시뮬레이션 가능
QA 효율 ↑	QA 엔지니어가 Swagger로 테스트 가능
운영 리스크 ↓	문서화와 실제 구현의 불일치 방지 가능

---

✅ 마무리 요약

항목 요약

적용 도구	springdoc-openapi 기반 Swagger UI
핵심 어노테이션	@Operation, @Schema, @ApiResponse
경로	/swagger-ui/index.html, /v3/api-docs
설정 포인트	전역 Info, DTO 스키마 설명, 그룹화
적용 범위	모든 API에 자동 문서화 적용 가능

---

📌 다음 편 예고

Spring Boot 시리즈 7편: API 응답 구조 표준화 – 성공/실패 응답 통일 설계 패턴