Swagger에서 VO/DTO를 표기하는 방법 / The way write VO/DTO in Swagger

Controller에서 어떠한 값을 request로 받는지, 어떻게하면 Swagger로 잘 표기하고 싶으실까? 에대한 고민을 하는 개발자분들이 많을 것입니다. 요청의 종류에 따라서 나누어서 설명드리고자 합니다.

​

1. Get방식의 @RequestParam 일경우

(@RequestParam은 Swagger의 기능이 아니니 다른 포스팅에서 다루도록 하겠습니다.)

(1) @RequestParam을 사용하시는 경우는 아래와 같이 parameter가 간단하신 경우이실 것입니다.

그러니까, 애초에 parameter가 복잡하셨으면 get으로 넘기지는 않으셨을 것이라고 예상됩니다. 복잡하셨으면 post로 class를 묶어서 전송하셨을 것이라고 생각됩니다.

그런 경우, Controller단에서 @ApiParam 이라는 Annotation을 사용해주시면 됩니다.

.
.
.
public getUserInfo(
.
.
@RequestParam
@ApiParam(name = "userId", value = "유저의 고유한 id값", required = true, example = "1")
long userId
) {
.
.
.
}

(물론 인증정보를 가져올때에는 RequestHeader로 token도 같이 넘겨야겠지만 현 포스팅의 주제와 맞지않으니 @ApiParam에만 집중하겠습니다)

 

 

2. Post방식

Post 방식의 경우 위에처럼 Controller단에 적어주는것이 아니라, Request Class 로 가셔서 정의해주셔야 합니다

만약 UserInfoRequest 라는 클래스를 하나 만들어서, 해당 형식대로 Client 개발자분에게 data를 받아야된다는 가정하에 예를 들어보겠습니다.

​

(1) (Class 위) @ApiModle

.
.
@ApiModel(value="UserInfoRequest", description = "유저 정보 관련 요청")
public class UserInfoRequest {
.
.
.
}

 

(2) (변수 하나하나씩, (1)번안에 작성해주시면 됩니다) @ApiProperty

.
.
@ApiModelProperty(
            value = "유저의 고유한 id값"
            , example = "1"
            , required = true
)
long userId;
.
.

 

감사합니다^^