Swagger 설정

1. @Api

---

기존에 작성한 controller에 @Api(tags = {""}를 추가하자. ""안에 간단한 tag를 입력할 수 있는데.

swagger ui에 보여지는 이름?이라고 보면 된다.

@Api(tags = {"API 정보를 제공하는 Controller"})
@RestController
@RequestMapping("/api")
public class Controller {

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

swagger-ui를 새로고침하면 이름이 바뀐걸 볼 수 있다.

2. @ApiParam

---

 

controller내에 pathVariable, query parameter을 변수로 받아 두 값을 더하는 method를 작성하자.

@GetMapping("/plus/{x}")
    public int plus(@PathVariable int x, @RequestParam int y){
        return x+y;
    }

 

실행 후 swagger-ui를 새로고침하면 plus method가 추가된걸 볼 수 있다.

 

빈간에 숫자를 넣어 실행해 볼 수 있다.

 

흠 그런데, x랑 y가 무슨 값을 의미하는지 모르겠다. 설명을 추가하기 위해서는 @ApiParam을 변수 앞에 붙여주자.

@ApiParam의 value에는 간단한 설명, defaultValue에는 기본값을 넣을 수 있다.

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

swagger ui를 재실행하면 description에  "x값"이 추가된 것을 볼 수 있다.

 

3. @ApiModelProperty

---

이전까지는 query parameter나 path variable로 값을 받아왔는데, object로 받아오는 경우에는 어떻게 할까..?

 

각  class에서 해당 변수에 @ApiModelProperty를 달아주면 된다.

 

먼저 dto package에 UserReq, UserRes class를 만들어주자. 

 

[UserReq]

@Data
@NoArgsConstructor
@AllArgsConstructor
public class UserReq {

    private String name;
    private int age;
    
}

[UserRes]

@NoArgsConstructor
@AllArgsConstructor
@Data
public class UserRes {

    private String name;
    private int age;

}

그리고 controller에는 UserReq를 받으면 해당 user의 name, age를 UserRes에 담아서 echo 형대로 return하는 method를 만들어 주자.

@GetMapping("/user")
    public UserRes user(UserReq userReq){
        return new UserRes(userReq.getName(), userReq.getAge());
    }

 

실행 후 swagger-ui를 새로고침하면 user method 가 추가된걸 확인할 수 있다.

 

흠 그런데 뭐 큰 설명은 달려있지 않다. 어떻게 추가할까.

설명을 추가하고 싶은 변수에 @ApiModelProperty를 붙여주자.

value에는 변수에 대한 설명, example은 사용예시, required는 값 입력이 필수인지 아닌지 

@Data
@NoArgsConstructor
@AllArgsConstructor
public class UserReq {

    @ApiModelProperty(value = "사용자 이름", example = "hyun", required = true)
    private String name;

    @ApiModelProperty(value = "사용자 나이", example = "29", required = true)
    private int age;

}

swagger-ui를 새로고침해보자. description에 사용자 나이, 사용자 이름이 추가되었다.

 

그리고 *required로 변경되었고, response화면에 예시로 사용된 값이 적용되었다.

description 추가됨

example입력한 값이  result 예시로 나옴

 

 

 

4.@ApiOpertaion

---

method에 대한 설명을 추가해보자. contorller의 user method에 @ApiOperation을 붙여주자.

@ApiOperation(value = "사용자 이름,나이를 리턴하는 method")
    @GetMapping("/user")
    public UserRes user(UserReq userReq){
        return new UserRes(userReq.getName(), userReq.getAge());
    }

swagger ui 를 새로고침 하면 user method에 설명이 변경된 것을 볼 수 있다.

 

5. @ApiResponse

---

response부분 하단에 보면 error가 발생 했을 때에 대한 경우도 있다.

해당 code에 대한 설명을 추가하기 위해서는, @ApiResponse를 활용하면 된다.

 

아래 처럼 입력해주면 사용자 나이가 10살 이하일 경우 502를 내려준다고 설명을 붙일 수 있다.

 @ApiResponse(code = 502, message = "사용자 나이 10살 이하일 때")
 @ApiOperation(value = "사용자 이름,나이를 리턴하는 method")
 @GetMapping("/user")
 public UserRes user(UserReq userReq){
 return new UserRes(userReq.getName(), userReq.getAge());
 }

502가 추가되었다.

 

6. post의 경우는?

---

Post method를 하나 작성해주자. UserReq를 받아서 UserRes에 name과 age를 올려서 return을 한다.

 @PostMapping("/user")
    public UserRes userPost(@RequestBody UserReq userReq){
        return new UserRes(userReq.getName(), userReq.getAge());
    }

swagger-ui를 새로고침하면 userPost가 추가된 것을 볼 수 있다.

post method가 추가됨

자세히 살펴보면 이전에 UserReq, UserRes에서 각 변수에 대해 @ApiModelProperty를 붙여줘서

example value에 적용된 것을 볼 수 있다.

post method이기 때문에 code 201도 적용이 되었다.

 

7. @ApiImplicitParams

---

get method의 경우  받아올 변수가 늘어나면 @ApiParam으로 하나하나 붙여주는건 귀찮다..

그럴땐 method에 바로 적용할 수 있는 방법이 있다.

 

@ApImplicitParams는 ApiImplicitParam을 배열의 형태로 받을 수 있다.

@ApiImplicitParam은 각각 변수 에 대한 설명을 추가해 줄 수 있다.

 

그러면 이전에 작성한 method에서 @ApiParam을 지우고 아래처럼 수정해주자.

 @ApiImplicitParams({
       @ApiImplicitParam(name = "x", value = "x 값", required = true, dataType = "int", paramType = "path"),
       @ApiImplicitParam(name = "y", value = "y 값", required = true, dataType = "int", paramType = "query")
    })
 @GetMapping("/plus/{x}")
 public int plus(@PathVariable int x, @RequestParam int y){
      return x+y;
    }

Swagger ui에서 살펴보면 이전에 @ApiParam으로 작성한 것과 동일한 화면을 보여준다.

 

이처럼 swagger ui를 사용하면 제3자가 이해하기 쉽도록 설명, 예시를 붙여줄 수 있다.