注释映射和豆类验证-DEV365 开发者社区

openapi-processor-spring/micronaut release 2022.5添加了新的注释类型映射功能。它提供了向生成的接口和类添加其他注释的可能性。

什么是OpenAPI-Processor？

openapi-processor是处理OpenAPI YAML文件的小框架。目前，OpenAPI-Processor为Spring Boot＆Micronaut提供Java代码生成。

它确实支持gradle和maven，其中包括插件，将OpenAPI YAML文件转换为Java（控制器）接口和（有效载荷）POJO类作为构建过程的一部分。

它会生成Java，因为控制器接口和POJO类很容易从其他JVM语言中使用。通常，您只会在不查看生成的代码的情况下使用它们。

注释映射

注释类型映射允许将注释添加到生成的模型类或该类的端点方法参数中。

让我们看一个人为的示例，以在模式的POJO模型类中添加自定义bean验证。

请参阅annotation mapping文档有关。

示例API

这是一个简单的API，它将Foo模式作为请求主体。该模式对其属性有一些（无用的;-)数字约束。

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中启用bean验证（处理器配置）将生成带有bean验证注释的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约束创建的BEAN验证注释。

自定义豆验证注释

现在，我们想添加一个验证，该验证通过编写@Sum(24)来检查两个Integer属性的总和。

让我们创建注释

手动创建自定义bean验证注释

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模型类中。

处理器配置映射.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 Schema生成的POJO模型类的给定注释，告诉处理器告诉处理器@nnotate @nnotate @nnotate the Foo schema（Foo是OpenAPI架构的名称）的注释映射。注释用完全合格的名称（需要创建导入）和（选择）和固定参数。

。

带有自定义注释的模型类

现在，在配置中的注释映射时，处理器将像这样生成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。