[Spring] Swagger 사용법

스웨거(Swagger)

API 자동 문서화 프레임 워크 (swagger.io/)

라이브러리 추가

build.gradle에 스웨거를 사용하기 위해 dependencies에 관련 라이브러리를 추가해줘야한다.

dependencies{
        //...
    implementation "io.springfox:springfox-swagger2:2.9.2"
    implementation "io.springfox:springfox-swagger-ui:2.9.2"
        //..
}

프로젝트 설정

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    //스웨거 페이지에 소개될 설명들
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Demo")
                .description("API EXAMPLE")
                .build();
    }

    @Bean
    public Docket commonApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("swg-group1")//빈설정을 여러개 해줄경우 구분하기 위한 구분자.
                .apiInfo(this.apiInfo())//스웨거 설명
                .select()//apis, paths를 사용하주기 위한 builder
                .apis(RequestHandlerSelectors.basePackage("com.sgw.web.controller"))//탐색할 클래스 필터링
                .paths(PathSelectors.any())//스웨거에서 보여줄 api 필터링
                .build();
    }
}

• 만약 위와 같이 설정하고 swagger-ui.html를 찾을 수 없다는 에러가 출력될경우 아래 설정도 추가해줘야한다. ()

@Configuration
public class SwaggerConfig extends WebMvcConfiguarationSupport {

    @Override
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

화면 예시

위와 같이 설정 할 경우 config에서 지정한 api에 대한 정보가

localhost:8080/swagger-ui.html에 접속하면 출력된다.

@Controller
@RequiredArgsConstructor
public class LoginController {

    private final UserService userService;
    private final PasswordEncoder passwordEncoder;

    @GetMapping("/signup")
    public String signupPage() {
        return "signup";
    }

    @ResponseBody
    @GetMapping("/checkNm/{nickNm}")
    public Boolean checkNickNm(@PathVariable(name = "nickNm") String nickNm) {
        User findUser = userService.findByNickNm(nickNm).orElse(null);
        if (findUser == null) {
            return true;
        }
        return false;
    }

    @ResponseBody
    @PostMapping("/signup")
    public User signup(@RequestBody SignupDtoRequest signupDtoRequest) {
        return userService.save(signupDtoRequest.toEntity(passwordEncoder));
    }
}

추가 설정

• @API : 해당 api 설명
• @ApiOperation
• @ApiImplicitParams
• @ApiIgnore : 명세서에 표시 하지 않음.
• @ApiModelProperty

@Api(value = "테스트 컨트롤러")
@Controller
public class TestController {

    @Builder
    @AllArgsConstructor
    @NoArgsConstructor
    @Getter
    static class TestResponse {
        @ApiModelProperty(value = "유저 번호",  dataType = "long", required = true)
        private Long userNo;
        @ApiModelProperty(value = "유저 이름",  dataType = "string")
        private String name;
        @ApiModelProperty(value = "유저 나이",  dataType = "integer")
        private Integer age;
    }

    @Builder
    @AllArgsConstructor
    @NoArgsConstructor
    static class TestRequest {
        private Long userNo;
        private String name;
        private Integer age;
    }

    @ApiOperation(value = "테스트 처리", tags = "테스트",
            httpMethod = "POST",
            response = TestResponse.class,
            notes = "테스트 v1 설명"
    )
    @ApiImplicitParams( value = {
            @ApiImplicitParam(name = "age", value = "유저 나이", required = true, dataType = "integer", paramType = "form"),
            @ApiImplicitParam(name = "name", value = "유저 이름", required = true, dataType = "string", paramType = "form"),
            @ApiImplicitParam(name = "userNo", value = "유저 번호", required = true, dataType = "long", paramType = "form")})
    @RequestMapping(value = "/test/v1", method =POST, consumes = "application/x-www-form-urlencoded")
    public TestResponse process(@ApiIgnore TestRequest testRequest) {
        TestResponse testResponse = TestResponse.builder()
                .userNo(1000L)
                .name("이름")
                .age(20)
                .build();
        return testResponse;
    }
}