(TIL) 20220127, Swagger 3.x 버전 사용법(Spring)

📕Facts(한 것)

---

• SwaggerUI 오류 해결 및 적용 완료(Swagger 3.0)
• 팀원 오류 수정

 

📕Findings(배운 것)

---

 

Swagger를 처음 사용해봐서 처음부터 공부가 필요했다.

처음에는 블로그를 참고해서 Swagger2.x 버전을 적용해서 사용했는데,

 

스프링과 충돌을 일으켜서 Swagger3.x 버전을 선택했다.

 

처음에는 swagger가 오류를 내뿜었다.

documentationPluginsBootstrapper error가 발생했다.

이 문제를 해결하는데는 방법이 여러개 있었다.

 

먼저 SwaggerConfig 클래스에 @EnableWebMv를 사용해서 에러를 잡는 방법이 있고,

다음은 application.properties 혹은 application.yml에 

 

// apllication.properties
spring.mvc.pathmatch.matching-strategy=ant_path_matcher

위 코드를 추가하는 방법이다.

 

하지만 문제는 해결되지 않았는데, SwaggerConfig 클래스에 잡아준 @EnableSwagger2 어노테이션 때문이었다.

 

사용한 버전은 3.x 버전이고 적용된건 2버전이기 때문이다.

그래서 이 어노테이션을 제거하니 모든 에러가 해결되었다.

 

 

---

적용한 Swagger 3.x 버전의 스프링 연동 방법을 알아보자.

 

먼저 gradle에 dependency를 추가한다.

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

2.x 버전은 이것 외에도 추가할게 더 있었지만

3.x 버전 부터는 모두 포함하고 있다.

 

그리고 SwaggerConfig 클래스를 생성해준다.

@Configuration
public class SwaggerConfig {

    private static final String API_NAME = "API 이름";
    private static final String API_VERSION = "0.0.1";
    private static final String API_DESCRIPTION = "설명";

    @Bean
    public Docket commonApi(){
        return new Docket(DocumentationType.OAS_30)
                .useDefaultResponseMessages(false)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("컨트롤러 위치"))
                .paths(PathSelectors.any())
                .build();
    }

    public ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title(API_NAME)
                .version(API_VERSION)
                .description(API_DESCRIPTION)
                .build();
    }

 

이렇게 생성해주면 된다.

 

2.x 버전의 경우 @EnableSwagger2 어노테이션이 @Configuration을 포함하고 있어서 @Configuration을 붙여주지 않아도 됐지만,

3.x 버전은 따로 Swagger에 관한 어노테이션이 없으므로 필요하다.

 

여기까지 설정하고 기본 주소인 http://localhost:8080/swagger-ui/index.html 로 접속하면 기본 화면이 출력되면서

컨트롤러들을 확인할 수 있다.

(2.x 버전의 경우 /swagger-ui.html이다.)

 

추가적으로 Controller에는

 	
    @ApiOperation(value = "사용자 이메일", notes = "DB에 입력된 이메일의 존재 여부를 리턴합니다.")
    @GetMapping("/emailCheck/{userEmail}")
    public ResponseEntity<Boolean> checkEmail(@PathVariable String userEmail) {
        return ResponseEntity.ok(userService.isDuplicateEmail(userEmail));
    }

@ApiOperation을 활용해서 어떤 메서드인지 알려주면 된다.

 

DTO도 설정이 가능한데,

@Getter
@AllArgsConstructor
@Builder
@NoArgsConstructor
@ApiModel("사용자 수정 정보")
public class UserModificationData {
    @NotBlank(message = "닉네임을 입력해주세요.")
    @Size(max=8)
    @Mapping("nickname")
    @ApiParam(value = "사용자 닉네임", example = "싱크싱크")
    private String nickname;

    @NotBlank(message = "비멀번호를 입력해주세요.")
    @Size(min=8)
    @Mapping("password")
    @ApiParam(value = "사용자 비밀번호", required = true, example = "test12345678")
    private String password;
}

 

이렇게 처리가 가능하다.

 

그러면

 

이런 광명을 찾을 수 있다.

 

📕Feeling(느낀 점)

---

삽질은 나를 성장하게 만들어 준다.

 

 

📕여담

---