[Spring] Swagger3 사용해보기

 

Swagger 란?

스웨거는 개발자가 REST 웹 서비스를 설계, 빌드, 문서화, 소비하는 일을 도와주는 대형 도구 생태계의 지원을 받는 오픈 소스 소프트웨어 프레임워크이다. - 위키

Swagger 2.x 버전을 적용할 수도 있고 3.x 버전을 적용할 수도 있습니다.

큰 차이는 없기 때문에 최신 버전인 Swagger 3.x 버전을 적용합니다.

 

Swagger 적용

 gradle 추가

implementation 'io.springfox:springfox-boot-starter:3.0.0'
implementation 'io.springfox:springfox-swagger-ui:3.0.0'

 

SwaggerConfig 생성

@Configuration
@EnableSwagger2
public class SwaggerConfig {

	@Bean
	public Docket api() {
		return new Docket(DocumentationType.SWAGGER_2)
			.select()
			.apis(RequestHandlerSelectors.any()) // 현재 RequestMapping으로 할당된 모든 URL 리스트를 추출
			.paths(PathSelectors.ant("/api/**")) // 그중 /api/** 인 URL들만 필터링
			.build();
	}
}

 

Controller 생성

@RequestMapping("/api/test")
@Api(tags = {"테스트 컨트롤러"})  //컨트롤러명 표시
@RestController
public class UserController {

	@ApiOperation("테스트메소드") // 메소드명 표시
	@GetMapping
	public String test(){
		return "tes";
	}
}

 

문서확인

http://localhost:8090/swagger-ui/

 

간단한 사용법

컨트롤러에 적용법은 위에서 보듯이 하면 되고 요구하는 Request 및 Response 명세서를 정의하는 방법입니다.

Controller

	@ApiOperation("DTO테스트") // 메소드명 표시
	@GetMapping
	public SwaggerDto test(@RequestBody SwaggerDto swaggerDto){
		return swaggerDto;
	}

 

DTO

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

@ApiModel("스웨거 DTO")
@Data
public class SwaggerDto {

	@ApiModelProperty("이름")  //필드의 명을 적을 수 있음
	private String name;

	@ApiModelProperty(value = "나이", required = true) //required 필수 여부를 표시
	private Integer age;

	@ApiModelProperty(value = "성별", example = "남 or 여") //example 예시를 표시
	private String gender;

	@ApiModelProperty(value = "휴대폰번호", hidden = true) // hidden 으로 감출수 있습니다.
	private String phone;
}

 

스웨거 확인

• 밑에보면 Request 와 200 OK 일경우 Response가 잘 표시되는 것을 확인할 수 있다.

 error 해결법

 버전에러

• 정확하게는 스프링부트 버전 3.x.x은 자바버전을 17을 사용해야하는데 자바 17버전에서는 스웨거가 정상적으로 돌아가지 않는다는 트러블 슈팅이 있었다.

스프링버전을 2.6.x , 자바11 로 낮춰서 해결

 

SpringBoot 2.6 이상 springfox-swagger3.0 적용 시 에러

spring boot 2.6.0부터 요청 경로를 ControllerHandler에 매칭시키기 위한 전략의 기본값이 ant_path_matcher 전략 -> path_pattern_parser 전략으로 변경되었기 때문이다.

• 에러 메세지

Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang
.NullPointerException: Cannot invoke "org.springframework.web.servlet.mvc.condition
.PatternsRequestCondition.getPatterns()" because "this.condition" is null

 

• 해결 방안 2가지

application.properties에서 spring.mvc.pathmatch.matching-strategy=ant_path_matcher로 default 값을 변경한다. spring boot의 버전을 2.5.x로 낮춘다.