[Spring Boot] Swagger, API 명세 자동화 하기

API 명세서를 처음에는 구글 스프레드 시트로 작성했다. 이러니까 공유하는 것에 불편함이 있어서 노션으로 바꾸었는데,

이러면 스프링에서 URI를 수정했을때 노션도 수동으로 수정해줘야 하는 번거로움이 있었다.

그래서 API 문서 자동화를 도와주는 툴인 Swagger를 도입했다.

 

# Gradle 의존성 추가

implementation group: 'io.springfox', name: 'springfox-boot-starter', version: '3.0.0'

3.0.0버전이 최신 버전인데 스프링과 호환 이슈가 조금 있는 것 같았다. 근데 저렇게 group, name, version을 명시하니 잘 호환되었다.

 

Swagger UI

그냥 Gradle만 도입하면 이렇게 디폴트 Swagger UI를 제공한다.

UI 접속 방법이 조금 삽질을 많이 했는데, 3.x버전은 접근 URI가 localhost:8080/swagger-ui/# 으로 접속해야한다.

커스텀 설정을 해주지 않으면 Swagger가 기본으로 제공하는 디폴트 UI를 보여준다.

 

# 커스터마이징

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket swagger() {
        return new Docket(DocumentationType.SWAGGER_2)
                .useDefaultResponseMessages(false)
                .ignoredParameterTypes(java.sql.Date.class, Member.class)
                .forCodeGeneration(true)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo())
                .enable(true);
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("TeamOne API 명세서")
                .description("TeamOne Controller API 요청, 응답 상세 명세")
                .build();
    }
}

이런 Config파일을 추가하면 커스터마이징을 할 수 있다.

ignoredParameterTypes에 Member.class를 추가했는데, 엔티티 클래스인 Member의 불필요한 정보가 모두 노출되서 출력되지 않도록 설정해준 것이다.

 

# 접속 경로 리다이렉트

@Controller
@ApiIgnore
public class SwaggerRedirector {
    @GetMapping("/api")
    public String redirect() {
        return "redirect:/swagger-ui/#";
    }
}

편의성을 위해 swagger-ui/#로 접속말고 /api로 접속하면 리다이렉트되도록 설정해주었다.

 

 

# Controller에 도입

@ApiOperation(value="평점(star) 변경")
@ApiResponses({
        @ApiResponse(code = 200, message = "평점 변경 성공"),
        @ApiResponse(code = 400, message = "평점 변경 실패")
})
@PutMapping("/star/{newStar}")
public ResponseEntity<?> updateStar(@Login Member loginMember, @PathVariable Double newStar) throws LoginException {
    signInService.loginCheck(loginMember);
    return RestResponse.success(memberService.updateStar(loginMember.getId(), newStar));
}

 

# 오류 해결

Cannot invoke "org.springframework.web.servlet.mvc.condition.PatternsRequestCondition.getPatterns()" because "this.condition" is null

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

해결 방법 : application 설정 파일에 다음을 추가한다

mvc:
  pathmatch:
    matching-strategy: ant_path_matcher