🌐 Spring Boot 프로젝트에 Swagger(OpenAPI) 적용하는 방법

✅ 1. Swagger(OpenAPI)란?

• Swagger는 API를 자동으로 문서화하고, 웹 UI에서 바로 테스트까지 할 수 있게 해주는 도구입니다.
• Spring Boot에서는 SpringDoc OpenAPI 라이브러리를 통해 손쉽게 적용할 수 있습니다.

---

✅ 2. Gradle 의존성 추가

build.gradle 파일에 아래 의존성을 추가합니다:

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

 

🔸 최신 Spring Boot 3.x 와 호환되는 버전입니다.
추가 후 Gradle Reload 또는 ./gradlew build 명령을 실행하세요.

---

✅ 3. Swagger UI 접속

Spring Boot 서버를 실행한 뒤, 브라우저에서 아래 주소로 접속합니다:

 

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

 

🧪 이 페이지에서 API 목록을 확인하고, 실제 요청 테스트도 가능합니다.

 

등록한 API들이 자동으로 정리되어 표시됩니다.

 

---

 

✅ 4. Swagger 문서 자동화 어노테이션 적용

📍 컨트롤러 상단에 그룹화 태그 추가:

@Tag(name = "UserController", description = "회원 관련 API")

📍 각 메서드에 설명 추가:

@Operation( summary = "회원가입", description = "이름과 이메일을 받아 새로운 사용자를 등록합니다." )

 

📍 파라미터에 설명 추가:

@Parameter(description = "조회할 회원 이메일 주소")

📍 전체 예시:

@PostMapping 
@Operation(summary = "회원가입", description = "이름과 이메일로 사용자 등록")
public ResponseEntity createUser( 
@RequestBody 
@Parameter(description = "회원 정보 DTO") UserDto request) { ... }

---

✅ 5. Swagger가 잘 작동하지 않을 때 (문제 해결 팁)

@Operation 빨간 줄	Gradle 프로젝트로 정상 등록되었는지 확인 (Add as Gradle Project)
작동은 되는데 빨간 줄	IntelliJ → File > Invalidate Caches / Restart
UI에 아무 것도 안 나옴	서버 실행 후 /swagger-ui/index.html 재확인

---

✅ 6. 실무에서 Swagger를 사용하는 이유

문서 자동화	API 변경 사항이 자동으로 반영됨
테스트 용이	프론트 없이도 API 테스트 가능
협업 효율	디자이너/기획자와 API 구조 공유
포트폴리오 어필	“Swagger 기반 API 문서 자동화 경험”은 면접에서 강점!

---

✨ 마무리

Swagger는 단순한 API 테스트 도구를 넘어서,
API 개발의 설계 → 문서화 → 테스트를 자동화하는 표준 툴입니다.

✅ 프로젝트를 처음부터 잘 설계하고 싶다면, Swagger 적용부터 시작하세요!