[Swagger] Spring 3.1.2에 Swagger 적용

Spring Boot로 Api서버를 만들때, 보기 편하라고 팀원과 이야기해서 API 명세서를 만들었다.
그런데 한 분이 API명세서를 Swagger라는 것으로 상당히 간단하게 만들 수 있다는 이야기를 해 주셨고, 생각난 김에 바로 찾아보고 적용해봤다.

결과는 참패.
적용이 죽어라고 안됐다. 엄청난 사투를 벌이던 중, 뭔가를 발견했다.

많은 Swagger 관련 글, 영상들에서는 springfox 라이브러리를 사용하는 것으로 소개가 되어있다.
여기서 중요한걸 놓쳤다. 그거슨 바로 나의 Spring Boot 버전..

Spring Boot 3.0.0 이상부터 springdoc-openapi-ui 라이브러리를 사용해야 함

뭔가 잘못됐음을 깨닳았다.

높디 높은 버전을 쓰고있었다. 나는 2.7.15를 쓰고 있었던줄로만 알았는데...
바로 pom.xml을 수정해줬다.

*springdoc 공식문서 참고

Dependency 추가

	// pom.xml	
  
  		<dependency>
			<groupId>org.springdoc</groupId>
			<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
			<version>2.2.0</version>
		</dependency>

SwaggerConfig 클래스 생성

Swagger를 쓰기위한 코드도 수정해줬다.
저장소 루트밑에 Config 패키지를 만들고 그 안에 SwaggerConfig 클래스를 만들어줬다.

@Configuration
@OpenAPIDefinition
public class SwaggerConfig {
    @Bean
    // localhost:xxxx/swagger-ui/index.html#/  << 접속경로
    public OpenAPI baseOpenAPI() {
        return new OpenAPI().info(new Info().title("제목").version("버전").description("설명"));
    }
}

Controller에 Annotation 추가

@Tag(name="태그 이름", description = "태그 설명")

이 @Tag를 묶고자 하는 Controller쪽에 붙혀서 그룹화 시킨다.
최소한 이 annotation을 붙혀줘야 동작이 되는 것 같다.
다시해보니 역시 알아서 컨트롤러를 찾고 표시해준다.

여기까지 됐으니 서버를 실행시키고 접속 경로로 들어가 봤다.

~ /swagger-ui/index.html#

위에있는 코드에 몇가지만 적어주면 깔끔하게 API명세서가 나온다. 테스트도 가능하다.
더 많은 annotation이 있고 쓰면 쓸수록 완성도가 높아지겠지만, 이거만 있어도 충분히 써먹을것같다..
짱좋다...ㅎ...

참고: Swagger Annotation 상세 설정법