주석 매핑 및 빈 유효성 검사

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 을 살펴보십시오.