Swagger UI

신규 API를 작성하여 배포할 일이 생겨 복습겸 스웨거 어노테이션을 정리하고자 한다.

@ApiOperation(
        value = "유저 정보 조회"
        , notes = "유저의 ID 를 통해 해당 아이디의 상세 정보 조회 한다.")
@ApiImplicitParams(
        {
            @ApiImplicitParam(
                name = "id"
                , value = "자격증 아이디"
                , required = true
                , dataType = "string"
                , paramType = "path"
                , defaultValue = "None"
            )
        ,
            @ApiImplicitParam(
                name = "fields"
                , value = "응답 필드 종류"
                , required = false
                , dataType = "string"
                , paramType = "query"
                , defaultValue = ""
            )
        })
		@ApiResponses({
        @ApiResponse(code = 200, message = "성공입니다.")
        , @ApiResponse(code = 400, message = "접근이 올바르지 않습니다.")
    })
    @GetMapping("/user/{id}")
    public  ResponseEntity<UserResponse> getUser(@PathVariable(name = "id") String id) {
        return userService.findUserInfoById(id);
    }

 

@ApiOperation = Method 설명

• Controlloer 안에 method 의 설명을 추가할 수 있다.

 

@ApiImplicitParam = RequestParaemter 설명

• 해당 API Method 호출에 필요한 Paraemter들의 설명르 추가할 수 있다.
• ApiImplicitParams을 통해 복수개의 정보를 사용 할 수 있다.

 

@ApiResponse = Response 설명

• 해당method의 Response에 대한 설명을 작성할 수 있다.
• 복수개의 Response 에 대한 설명을 추가하고 싶다면, ApiResponse를 통해 사용 가능하다.

 

 

스웨거의 기본 Response message 삭제방법

 

• 위와 같이 기본 response 가 노출이 되는데 이를 제거 하기 위헤서는 Swagger config에 Docket에 useDefaultResponseMessages(false)를 설정해주면 된다. (설정 시 401, 403, 404 응답이 사라진다.)

@Getter
@Setter
@NoArgsConstructor
@AllArgsConstructor
@ToString
public class UserRequest {
    
    @ApiModelProperty(
        name = "id"
        , example = "gillog"
    )
    @ApiParam(value = "사용자 ID", required = true)
    private String id;

		@ApiModelProperty(example = "teter문")
    @ApiParam(value = "사용자 이름")
    private String name;

    @ApiParam(value = "token 갱신 값")
    private String tokenRefresh;
}

 

@ApiModelProperty = DTO 예제 설명

• ApiModelProperty를 DTO Class Field에 추가하면, 해당 DTO Field의 예제 Data를 추가할 수 있다.
• property의 name은 생략할 수 있다.

@ApiParam = DTO field 설명

• DTO field에 대한 설명을 추가할 수 있다.
• Controlloer PathVarialbe 기타 파라메터에 대한 설명도 추가 가능

    @ApiIgonre
		@GetMapping("/user/{id}")
    public  ResponseEntity<UserResponse> getUser(@PathVariable(name = "id") String id) {
        return userService.findUserInfoById(id);
    }

 

@ApiIgnore Swagger UI 표기제외

• Controller 나 메소드를 스웨거 상 비노출 처리 할 수 있다.
• ApiOperation 옵션 hidden을 true로 만들어서 엔드포인트를 숨길 수 있다.