Spring Boot Swagger 3.x 사용

1. Swagger 적용

1) Swagger란?

: 개발한 REST API를 편리하게 문서화 해주고, 이를 통해서 관리 및 제 3의 사용자가 편리하게 API를 호출해보고 테스트 할 수 있는 프로젝트이다

 

2) Spring Boot에서는 gradle dependencies에 추가하여 사용

/* build.gradle */

dependencies {
    ...//https://mvnrepository.com/artifact/io.springfox/springfox-boot-starter
    implementation group: 'io.springfox', name: 'springfox-boot-starter', version: '3.0.0'
}

!주의 Spring 버전이 3.0이상인 경우 에러 발생 2.x.x로 낮추어 depency 적용하니 정상 Swagger 페이지 확인

Springfox-boot-Starter 3.0.0

3) Swagger Annotation

@Api : 클래스를 스웨거의 리소스로 표시

@ApiOperation : 특정 경로의 오퍼레이션 HTTP 메소드 설명

@ApiParam : 오퍼레이션 파라미터 메타 데이터 설명

@ApiResponse : 오퍼레이션 응답 지정

@ApiMoelProperty : 모델의 속성 데이터를 설명

@ApiImplicitParam, @ApiImplicitParmas : 메소드 단위의 오퍼레이션 파라미터를 설명

2. Swagger 설정 하는 Config

1) Config

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@Configuration
public class SwaggerConfig{

    /*
     * Docket: Swagger 설정의 핵심이 되는 Bean
     * useDefaultResponseMessages: Swagger 에서 제공해주는 기본 응답 코드 (200, 401, 403, 404). false 로 설정하면 기본 응답 코드를 노출하지 않음
     * apis: api 스펙이 작성되어 있는 패키지 (Controller) 를 지정
     * paths: apis 에 있는 API 중 특정 path 를 선택
     * apiInfo:Swagger UI 로 노출할 정보
     *
     */
    @Bean
    public Docket api(){
        return new Docket(DocumentationType.OAS_30)
                .useDefaultResponseMessages(false)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.swagger.controller"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("Swagger Test : ")
                .description("Test config : ")
                .version("1.1")
                .build();
    }
}

2) RequestDto

import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;

@AllArgsConstructor
@NoArgsConstructor
@Data
public class UserReq {

    @ApiModelProperty(value="이름", example="박씨", required = true)
    private String name;
    @ApiModelProperty(value="나이", example="20", required = true)
    private int age;
}

3) ResponseDto

import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;

@AllArgsConstructor
@NoArgsConstructor
@Data
public class UserRes {
    @ApiModelProperty(value="이름", example="장씨", required = true)
    private String name;
    @ApiModelProperty(value="나이", example="30", required = true)
    private int age;
}

3. Controller에 Swagger Annotation 적용

@Api(tags = {"API Info for Controller"})
@RestController
@RequestMapping("/api")
public class ApiController {

    @GetMapping("/hello")
    public String hello(){
        return "name";
    }

    @GetMapping("/path/{x}")
    public int plus(@ApiParam(value="x값")
                    @PathVariable int x,
                    @ApiParam(value="y값")
                    @RequestParam int y){
        return x+y;
    }

    @ApiOperation(value="사용자의 이름과 나이를 return")
    @ApiResponses({
            @ApiResponse(responseCode ="200", description = "OK"),
            @ApiResponse(responseCode ="400", description = "Bad Request"),
            @ApiResponse(responseCode ="404", description = "Not Found"),
            @ApiResponse(responseCode ="500", description = "Internal Server Error")
    })
    @ApiImplicitParams({
            @ApiImplicitParam(name="age", dataType = "int", required = true, paramType = "query"),
            @ApiImplicitParam(name="name", dataType = "string", required = true, paramType = "query")
    })
    @GetMapping("/user")
    public UserRes userGet(UserReq userReq){
        return new UserRes(userReq.getName(), userReq.getAge());
    }

    @ApiOperation(value="Post 사용자의 이름과 나이를 return")
    @ApiResponses({
            @ApiResponse(responseCode ="200", description = "OK"),
            @ApiResponse(responseCode ="400", description = "Bad Request"),
            @ApiResponse(responseCode ="404", description = "Not Found"),
            @ApiResponse(responseCode ="500", description = "Internal Server Error")
    })
    @PostMapping("/user")
    public UserRes userPost(@RequestBody UserReq userReq){
        return new UserRes(userReq.getName(), userReq.getAge());
    }

}

4. localhost:port/swagger-ui/index.html#/ 접속

index.html

parameter 입력