[Spring] Swagger

Swagger란?

• Swagger란 개발한 REST API를 편리하게 문서화해주고, 이를 통해서 관리 및 제3의 사용자가 편리하게 API를 호출해보고 테스트 할 수 있는 프로젝트이다.
• Spring Boot에서는 간단하게 springfox-boot-starter를 gradle dependencies에 추가함으로 사용할 수 있다.
• 다만, 주의할 점은 운영환경과 같은 외부에 노출되면 안되는 곳에는 사용할 땐 주의해야 한다.
  
• controller 예제코드

	// swagger 활용 부분
    @GetMapping("/plus/{x}") // 그러나 @ApiParam(value = "x값") 이렇게 붙여주는건 다소 불편할 수 있음
    public int plus(
            @ApiParam(value = "x값")
            @PathVariable int x,

            @ApiParam(value = "y값")
            @RequestParam int y){
        return x + y;
    }

    @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 apiUpgradePlus(@PathVariable int x, @RequestParam int y){
        return x + y;
    }

    @ApiResponse(code = 502, message = "사용자의 나이가 10살 이하일때")
    @ApiOperation(value = "사용자의 이름과 나이를 echo하는 메소드")
    @GetMapping("/swagger-user")
    public UserRes user(UserReq userReq){
        return new UserRes(userReq.getName(), userReq.getAge());
    }

    @PostMapping("/swagger-post")
    public UserRes postUser(@RequestBody UserReq req){
        return new UserRes(req.getName(), req.getAge());
    }

• data 객체 예제코드

@Data
@AllArgsConstructor
@NoArgsConstructor
public class UserReq {

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

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

다음과 같은 페이지로 API 문서를 편리하게 만들 수 있다.

출처 : 한 번에 끝내는 Java/Spring 웹 개발 마스터 초격차 패키지 Online.