주석 매핑 및 빈 유효성 검사

openapi-processor-spring/micronaut release 2022.5은 새로운 주석 유형 매핑 기능을 추가합니다. 생성된 인터페이스 및 클래스에 추가 주석을 추가할 수 있는 가능성을 제공합니다.

openapi-processor란 무엇입니까?

openapi-processor은 OpenAPI yaml 파일을 처리하기 위한 작은 프레임워크입니다. 현재 openapi-processor는 Spring Boot 및 Micronaut에 대한 Java 코드 생성을 제공합니다.

빌드 프로세스의 일부로 OpenAPI yaml 파일을 Java(컨트롤러) 인터페이스 및 (페이로드) pojo 클래스로 변환하는 플러그인으로 gradle 및 maven을 지원합니다.

컨트롤러 인터페이스와 pojo 클래스는 다른 jvm 언어에서 쉽게 사용할 수 있기 때문에 Java를 생성합니다. 일반적으로 생성된 코드를 보지 않고 그냥 사용하게 됩니다.

주석 매핑

주석 유형 매핑을 사용하면 생성된 모델 클래스 또는 해당 클래스의 끝점 메서드 매개 변수에 주석을 추가할 수 있습니다.

스키마의 pojo 모델 클래스에 커스텀 빈 유효성 검사를 추가하기 위해 고안된 예제를 살펴보겠습니다.

자세한 내용은 annotation mapping 설명서를 참조하십시오.

예제 API

다음은 Foo 스키마를 요청 본문으로 사용하는 간단한 API입니다. 스키마에는 속성에 대한 몇 가지 (쓸모없는 ;-) 숫자 제한이 있습니다.

openapi.yaml

openapi: 3.1.0 info: title: annotation mapping example version: 1.0.0 paths: /foo: post: summary: annotation mapping example endpoint. description: a simple endpoint where an annotation mapping is used on the request body requestBody: content: application/json: schema: $ref: '#/components/schemas/Foo' required: true responses: '201': description: empty response components: schemas: Foo: type: object properties: foo1: type: integer minimum: 0 foo2: type: integer minimum: -10 

빈 유효성 검사 주석

mapping.yaml(프로세서 구성)에서 빈 유효성 검사를 활성화하면 속성 제약 조건에 대한 빈 유효성 검사 주석이 있는 Foo 클래스가 생성됩니다.

생성된 파일

package io.openapiprocessor.openapi.model; import com.fasterxml.jackson.annotation.JsonProperty; import io.openapiprocessor.openapi.support.Generated; import javax.validation.constraints.DecimalMin; @Generated(value = "openapi-processor-spring", version = "2022.5") public class Foo { @DecimalMin(value = "0") // <1> @JsonProperty("foo1") private Integer foo1; @DecimalMin(value = "-10") // <1> @JsonProperty("foo2") private Integer foo2; public Integer getFoo1() { return foo1; } public void setFoo1(Integer foo1) { this.foo1 = foo1; } public Integer getFoo2() { return foo2; } public void setFoo2(Integer foo2) { this.foo2 = foo2; } } 

<1> OpenAPI 제약 조건에서 생성된 빈 유효성 검사 주석입니다.

커스텀 빈 검증 어노테이션

이제 Integer 를 작성하여 두 가지@Sum(24) 속성의 합계를 확인하는 유효성 검사를 추가하고 싶습니다.

주석을 만들어 봅시다

수동으로 생성된 커스텀 빈 유효성 검사 주석

package io.openapiprocessor.samples.validations; import javax.validation.Constraint; import javax.validation.Payload; import java.lang.annotation.*; @Constraint (validatedBy = {FooSumValidator.class}) @Target ({ ElementType.TYPE, ElementType.PARAMETER }) @Retention (value = RetentionPolicy.RUNTIME) public @interface Sum { String message () default "invalid sum"; Class<?>[] groups () default {}; Class<? extends Payload>[] payload () default {}; int value(); } 

그리고 유효성 검사 코드.

수동으로 생성된 검증

package io.openapiprocessor.samples.validations; import io.openapiprocessor.openapi.model.Foo; import javax.validation.ConstraintValidator; import javax.validation.ConstraintValidatorContext; public class FooSumValidator implements ConstraintValidator<Sum, Foo> { private Integer sum; @Override public void initialize (Sum constraintAnnotation) { sum = constraintAnnotation.value (); } @Override public boolean isValid (Foo value, ConstraintValidatorContext context) { return value.getFoo1 () + value.getFoo2 () == sum; } } 

사용자 지정 주석에 대한 매핑

이제 생성된Foo pojo 모델 클래스에 맞춤형 주석을 추가하도록 프로세서에 지시하는 주석 유형 매핑이라는 흥미로운 부분이 있습니다.

프로세서 구성 mapping.yaml

openapi-processor-mapping: v2.1 # <1> options: package-name: io.openapiprocessor.openapi bean-validation: true map: types: # <2> - type: Foo @ io.openapiprocessor.samples.validations.Sum(24) 

<1> 새로운 매핑 버전. 다른 버전을 사용하면 매핑이 잘못되었다는 경고가 생성됩니다.

<2> Foo 스키마(Foo는 OpenAPI 스키마의 이름임)를 Foo 스키마에 대해 생성된 pojo 모델 클래스에 지정된 주석으로 @nnotate하도록 프로세서에 알리는 주석 매핑입니다. 주석은 정규화된 이름(가져오기를 만드는 데 필요함) 및 (선택 사항) 고정 매개변수와 함께 제공됩니다.

사용자 지정 주석이 있는 모델 클래스

이제 구성의 주석 매핑을 사용하여 프로세서는 다음과 같이 생성합니다Foo.

사용자 지정 주석이 있는 생성된 파일

package io.openapiprocessor.openapi.model; import com.fasterxml.jackson.annotation.JsonProperty; import io.openapiprocessor.openapi.support.Generated; import javax.validation.constraints.DecimalMin; import io.openapiprocessor.samples.validations.Sum; @Sum(24) // <1> @Generated(value = "openapi-processor-spring", version = "2022.5") public class Foo { @DecimalMin(value = "0") @JsonProperty("foo1") private Integer foo1; @DecimalMin(value = "-10") @JsonProperty("foo2") private Integer foo2; public Integer getFoo1() { return foo1; } public void setFoo1(Integer foo1) { this.foo1 = foo1; } public Integer getFoo2() { return foo2; } public void setFoo2(Integer foo2) { this.foo2 = foo2; } } 

<1> 사용자 지정 빈 유효성 검사 주석.

요약

이 작은 기사에서는 프로세서 매핑 구성에 주석 유형 매핑을 추가하여 생성된 클래스에 사용자 지정 주석을 추가하는 방법을 설명했습니다.

openapi-processor 및 OpenAPI 설명에서 컨트롤러 인터페이스 및 모델 클래스를 생성하는 방법에 대해 자세히 알아보려면 documentation 을 살펴보십시오.