P3] Ch 09. Swagger를 통한 API 공개

uuuu.jini·2022년 1월 18일

Spring Framework - 강의 정리본

목록 보기

7/18

1. Swagger 란?

개발한 REST API를 편리하게 문서화 해주고, 이를 통해 관리하거나 제 3자의 사용자가 편리하게 API를 호출해보고 테스트할 수 있게 해준다. gradle dependencies에 springfox-boot-starter를 추가해줌으로써 쉽게 사용할 수 있다. 외부에 노출되면 안되는 곳에서 사용할 때에는 주의하여야 한다.

2. Swagger 설정하기

Failed to start bean 'documentationPluginsBootstrapper' 에러 발생 하여 dependency 버전이 맞지 않는 것 확인하였다.
springframwork.boot의 버전을 2.4.5로 바꿔주니 잘됨,,

localhost:8080/swagger-ui/를 들어가서 swagger를 확인가능하다.

해당 페이지에서 요청하고 응답한 값을 확인하는 것을 쉽게 할 수 있다.

@Api

컨트롤러로 사용하는 클래스위에 작성하며 tags 속성으로 넘긴 값이 해당 컨틀로러의 설명이 된다.
@Api(tags = {"API 정보를 제공하는 Controller"})

@ApiParam

해당 파라미터 앞에 작성하며, 파라미터의 이름(value),데이터타입 등과 같은 속성을 설정해준다. 각각의 파라미터에 따로 설정하여 사용한다.

@GetMapping("/plus/{x}")
    public int plus(
                    @ApiParam(value = "x값") 
                    @PathVariable int x,

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

@ApiImplicitParams와 @ApiImplicitParam

위와 동일한 설정을 메소드단위로 배열로서 설정이 가능하다. 위와 같이 각 파라미터 변수앞에 작성하는 것이 아닌 메소드위에 작성함으로써 간편하게 설정이 가능하다.

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

@ApiImplicitParam의 배열을 @ApiImplicitParams의 매개변수로 넣어서 작성하며, 각각의 @ApiImplicitParam에는 각 파라미터의 속성 설정이 들어간다.

@ApiOperation

해당 메소드의 설명을 설정해주는 어노테이션이다. 예로 @ApiOperation(value = "사용자의 이름과 나이를 echo 하는 메소드") 처럼 작성하며 value속성이 해당 메소드의 설명이 된다.

@ApiResponse

해당 메소드의 응답에 대해 추가하고 설명을 작성할 수 있게 해주는 어노테이션으로서 예로 @ApiResponse(code = 502,message = "사용자의 나이가 10살 이하일때")처럼 작성하면 응답이 "사용자의 나이가 10살 이하일때" 502코드가 내려갈 것이다라는 것을 보여줄 수 있다.

@ApiModelProperty

요청 또는 응답하는 객체의 변수 속성 데이터의 설명을 위한 어노테이션으로 해당 객체의 변수에 어노테이션을 각각 작성하여 준다.

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

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