Swagger 잘~만들어보기 응답 Model 명확하게, 타입, 최대 최소값 표출하기

Swagger는 API를 구현할 때 Front-End와 의사소통에 있어 많은 편의를 줍니다.

하지만 적절한 정보 규격을 전달해주지 않으면 많은 오해가 생기게 됩니다.

API 사용자와 보다 적절한 의사소통을 하기위해서 설정해줘야 하는 부분을 알아보도록 하겠습니다.

swagger를 적용하는 방법은 아래의 Link를 확인하세요!

 

Link : https://aljjabaegi.tistory.com/668

[API documentation 자동화] spring boot swagger UI 적용 방법

 

1. 응답 구조체를 명확하게 설정한다.

Json은 String 이 맞습니다. 하지만 리턴타입을 ResponseEntity<String>,

이렇게 설정하고 아래와 같이 리턴한다면 API 사용자 입장에서는 요청 시 전달받은 데이터의 구조를 알 수가 없습니다.

 

return ResponseEntity.ok()
              .body(new Gson.toJson(ApiResponse.builder()
                        .status(resultCode)
                        .message(resultMsg)
                        .size(size)
                        .items(rows)
                        .build()));

 

swagger 출력 결과 (string으로 표출)

string으로 나와 구조체를 알수 없음

구조체를 명확하게 설정

ResponseEntity<APIResponse<UserVO>> 처럼 리턴타입을 명확하게 설정

return ResponseEntity.ok()
                     .body(ApiResponse.<UserVO>builder()
                                .status(resultCode)
                                .message(resultMsg)
                                .size(size)
                                .items(rows)
                                .build());

응답 객체를 명확하게 설정해주면 swagger로 모델을 명확하게 표출해줍니다.

그리고 Controller에 리턴 타입을 Json 으로 설정합니다. 

 

produces = MediaType.APPLICATION_JSON_VALUE

 

 

2. 전달하고자 하는 명칭이 다를 경우 @JsonProperty를 사용한다.

예를들어 birthDt라는 컬럼을 birdhDay 로 변경하고 싶을 경우 아래와 같이 활용합니다.

import com.fasterxml.jackson.annotation.JsonProperty;

@JsonProperty("birthDay")
private String birdthDt;

 

 

3. 필수값을 설정한다.

필수 값인 경우 @JsonProperty(required = true) 옵션을 주거나

spring-boot-starter-validation의 @NotNull annotation을 추가해서 필수 값 임을 표시해줍니다.

 

import javax.validation.constraints.NotNull;
import com.fasterxml.jackson.annotation.JsonProperty;

@Getter
@Setter
@ToString
public class UserVO {
    private String userId;
    private String userName;
    @NotNull
    private String email;
    @JsonProperty(required = true)
    private String mobile;
    private Boolean isUse;
    private String birthDt;
    private String regDtm;
    private String udtDtm;
}

 

4. 데이터의 길이를 설정한다.

저장이나 수정 시 길이를 벗어나게 되면 DB관련 에러를 보실 수 있습니다. 

이럴 경우를 대비하여 String type에는 @Size

숫자형 type에는 @Max @Min Annotation를 추가해줍니다.

 

import javax.validation.constraints.Max;
import javax.validation.constraints.Min;
import javax.validation.constraints.Size;

@Getter
@Setter
@ToString
public class UserVO {
    private String userId;
    @Size(min = 3, max = 15)
    private String userName;
    private String email;
    private String mobile;
    private Boolean isUse;
    private String birthDt;
    private String regDtm;
    private String udtDtm;
    @Min(14)
    @Max(99)
    private int age;
}

 

 

5. Controller 와 Model 의 명칭 혹은 설명을 추가해준다.

Controller에는 @Api 를, DTO, VO에는 @ApiModel을 추가해줍니다.

 

[Controller]

@Api(tags = {"회원가입, 비밀번호 갱신, 유효성검증 API"})
public class UserController {
}

[Model]

@ApiModel(value = "UserInsDTO - 회원가입용 DTO")
public class UserInsDTO {
}

 

6. Model에 example을 추가해준다.

DTO나 VO의 변수에 @ApiModelProperty(example = "") 을 추가하여 실제 데이터가 어떻게 표출되는지 보여줍니다.

 

@ApiModelProperty(value = "email - 마스킹", example = "geon***************")
private String email;

이렇게 설정할 경우 Operation의 Parameter Value 아래와 같이 표출되지 않고,

{

    "email" : "String"

}

아래와 같이 표출됩니다.

{

    "email" : "geon***************"

}

 

 

지금까지 API 사용자와 인터페이스를 용이하게 할 수 있는 swagger 설정 방법을 알아보았습니다.

추가적으로 좋은 사항이 있으면 업데이트 하도록 하겠습니다.