1. 개요
이 사용방법(예제)에서는 Swagger의 @ApiParam 및 @ApiModelProperty 어노테이션 을 간략하게 살펴봅니다 . 또한 이러한 어노테이션을 비교하고 각각에 대한 올바른 사용법을 식별합니다.
2. 주요 차이점
간단히 말해서 @ApiParam 및 @ApiModelProperty 어노테이션은 Swagger에 다른 메타데이터를 추가합니다. @ApiParam 어노테이션은 API 리소스 요청의 매개변수용이고 @ApiModelProperty 는 모델 속성용입니다.
3. @ApiParam
@ApiParam 어노테이션은 @PathParam , @QueryParam , @HeaderParam , @FormParam 및 @BeanParam 과 같은 JAX-RS 1.x/2.x 매개변수 어노테이션 에만 사용 됩니다. swagger-core 는 기본적으로 이러한 어노테이션을 스캔하지만 @ApiParam을 사용 하여 매개 변수에 대한 세부 정보를 추가하거나 코드에서 읽을 때 값을 변경할 수 있습니다.
@ApiParam 어노테이션은 매개변수의 이름, 유형, 설명(값) 및 예제 값을 지정하는 데 도움이 됩니다 . 또한 매개변수가 필수인지 선택인지 지정할 수 있습니다.
사용법을 살펴보겠습니다.
@RequestMapping(
method = RequestMethod.POST,
value = "/createUser",
produces = "application/json; charset=UTF-8")
@ResponseStatus(HttpStatus.CREATED)
@ResponseBody
@ApiOperation(value = "Create user",
notes = "This method creates a new user")
public User createUser(
@ApiParam(
name = "firstName",
type = "String",
value = "First Name of the user",
example = "Vatsal",
required = true)
@RequestParam String firstName) {
User user = new User(firstName);
return user;
}@ApiParam 예제 에 대한 Swagger UI 표현을 살펴보겠습니다 .
이제 @ApiModelProperty 를 살펴 보겠습니다 .
4. @ApiModelProperty
@ApiModelProperty 어노테이션 을 사용 하면 설명(값), 이름, 데이터 유형, 예제 값 및 모델 속성에 허용되는 값과 같은 Swagger 관련 정의를 제어할 수 있습니다.
또한 특정 시나리오에서 속성을 숨기려는 경우 추가 필터링 속성을 제공합니다.
User's firstName 필드 에 몇 가지 모델 속성을 추가해 보겠습니다 .
@ApiModelProperty(
value = "first name of the user",
name = "firstName",
dataType = "String",
example = "Vatsal")
String firstName;이제 Swagger UI에서 사용자 모델의 사양을 살펴보겠습니다 .
5. 결론
이 빠른 문서에서는 매개 변수 및 모델 속성에 대한 메타데이터를 추가하는 데 사용할 수 있는 두 가지 Swagger 어노테이션을 살펴보았습니다. 그런 다음 해당 어노테이션을 사용하는 일부 샘플 코드를 살펴보고 Swagger UI에서 해당 표현을 확인했습니다.
항상 그렇듯이 이러한 모든 코드 샘플은 GitHub 에서 사용할 수 있습니다 .
