# Spring Boot Maven 프로젝트에서 Swagger UI 적용하기 (springdoc-openapi 설정법)

시작하기 전

Spring Boot 프로젝트에서 API 문서를 자동으로 만들어주는 Swagger UI는 개발 협업과 테스트에 큰 도움이 됩니다.
저는 Maven 환경에서 springdoc-openapi를 적용한 과정을 정리해보았습니다.

1. pom.xml 설정

<dependencies> ... </dependencies> 안에 Swagger 의존성을 추가합니다.

<dependencies>
...
</dependencies> 아래에

<!-- # 중앙 저장소(repository) 명시적으로 추가 -->
	<repositories>
		<repository>
			<id>central</id>
			<name>Maven Central Repository</name>
			<url>https://repo1.maven.org/maven2</url>
		</repository>
	</repositories>

만약 dependency not found 같은 에러가 발생한다면,
중앙 저장소(repository)를 못 찾는 경우이므로 위 repositories 코드를 추가한 뒤 Maven Reload를 해주면 정상적으로 동작합니다.

<!-- # Swagger (springdoc-openapi-ui) -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.3.0</version>
</dependency>

 

2. application.properties 추가

# Swagger UI
springdoc.api-docs.path=/v3/api-docs
springdoc.swagger-ui.path=/swagger-ui.html

 

기본 path는 원하는 대로 바꿀 수 있습니다.
저는 swagger-ui.html로 지정했기 때문에, 아래 주소로 접속하면 Swagger UI 화면을 확인할 수 있습니다.

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

 

---

Swagger UI 활용하기

정상적으로 접속하면, API가 자동으로 문서화된 화면이 나타납니다.

 

 

API 설명은 Controller 코드에 @Operation 어노테이션을 활용해서 추가할 수 있습니다.

@Operation(summary = "유저 업데이트", description = "유저 정보를 업데이트합니다.")
@PostMapping("/update")
public ResponseEntity<UserDTO> updateUser(@RequestBody UserDTO dto) {
    ...
}

이렇게 작성하면 Swagger UI에 **제목(summary) + 설명(description)**이 함께 표시되어, 협업 시에 매우 유용합니다.

 

Try it out 버튼을 누르면 브라우저에서 직접 API 요청을 테스트할 수 있습니다.

 

 

Maven 환경에서도 springdoc-openapi 라이브러리만 추가하면 손쉽게 Swagger UI를 적용할 수 있습니다.
API 테스트, 협업, 문서화를 한 번에 해결할 수 있으니 꼭 도입해보시길 추천드립니다.