REST API request별 swagger3.0.0 파라미터 명세

 

 

 

 

REST API를 개발하던 중 파라미터를 swagger3.0.0 에 명세해야 했습니다.

그런데 경우에 따라 조금씩 다르더라구요.

유형별로 명세 방식을 알아보겠습니다!

 

 

 

1. Path Variable

localhost:8080/userinfo/userid/{userId}/password/{password}

 

Path Variable 방식으로 들어오는 파라미터는 @Parameter, @PathVariable 어노테이션을 통해 설명과 Variable 종류를 명세해줍니다.

@Operation은 API에 대한 명세입니다.

 

전

 

후

 

 

 

 

 

2. Query Parameter

localhost:8080/userinfo/userid/{userId}/password/{password}?phoneNo=01012345678&birthY=1996

 

?물음표 뒤로 들어오는 Query Parameter는 Path Variable 과는 조금 다르게 객체를 만들어서 처리합니다. 하지만 그냥 객체만 추가하고 어노테이션을 추가하지 않으면 swagger 에서 단순히 json 형식으로만 보여줍니다.

그래서 @ParameterObject 를 통해 이 객체도 파라미터라는 것을 알려주고, @Parameter로 명세합니다.

 

전 (객체만 추가)

 

후

 

 

 

 

3. Json body

localhost:8080/userinfo/userid/{userId}/password/{password}

{

        "name" : "홍길동"

        "region" : "서울시"

}

 

Json body 로 들어오는 것은 방금 본 Query Parameter 처리 방식과 똑같습니다. @RequestBody 는 swagger를 위한 것은 아니고 body에 있는 데이터를 객체의 변수와 매핑하는데 사용합니다.

 

전 (객체만 추가)

 

후