Spring Boot 3에서 Swagger 사용하기

Swagger는 서버로 요청되는 API 리스트를 화면으로 문서화하여 테스트할 수 있는 라이브러리이다.

애플리케이션의 서버가 가동되면 @RestController를 읽어 API를 분석하여 HTML 문서를 작성한다.

현시점(2024-08-24) 가장 최신 버전은 2.6.0 버전이며, 버전 정보는 아래 링크에서 확인할 수 있다.

Spring Boot 3 버전에서 Swagger를 사용을 위한 가이드이며, 필자는 Maven을 사용하고 있다.

Gradle을 사용하는 분은 위 링크에서 Gradle 탭에 있는 코드를 참고하길 바란다.

다음 코드를 pom.xml과 application.properties에 추가한다.

pom.xml

<dependency>
	<groupId>org.springdoc</groupId>
	<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
	<version>2.6.0</version>
</dependency>

application.properties

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

여기까지 하면 swagger를 사용하기 위한 준비는 모두 끝났다.

http://localhost:8080/swagger-ui.html로 접속해 보면 swagger 페이지를 볼 수 있을 것이다.

추가적으로, 우리가 작성한 API를 좀 더 친절하게 정리하기 위해 몇 가지 어노테이션을 사용할 수 있으며, 아래는 그에 대한 예시이다.

@Operation(summary=API메소드 간략설명, description=자세한 설명)
@Tag(name=swagger에 표시할 그룹 이름, description=설명)

@Tag로 해당 컨트롤러가 어떤 컨트롤러인지 좀 더 친절한 설명(description)을 덧붙일 수 있다.

또한, @Operation을 지정하여 /board/inser라는 API 주소가 어떤 요청을 하는지 간략하게 summary를 볼 수 있으며 클릭 시 자세한 description도 볼 수 있다.

마지막으로, @ApiResponses 설정을 통해 각 응답 코드별 설명도 작성하여 좀 더 친절한 문서를 만들 수 있다.

@ApiResponse(responseCode=상태코드, description=설명, content=타입/스키마정의)

티스토리툴바