什么是 OpenApi-Processor ？ openapi-processor是一种易于使用的工具，可生成基于Java的（注释）Controller interfaces 和 pojos （模型类） 。它支持 spring boot ， micronaut maven 或 gradle 。。
假设我们有一个简单的（但没有用;-) OpenAPI描述。它使用自定义整数format来指定整数参数和响应代表a 年。
openapi: 3.1
info:
title: pending API
version: 1.0.0
paths:
/query:
get:
description: echo query parameter with type mapping
parameters:
- name: year
description: the year
in: query
required: true
schema:
type: integer # <1>
format: year
responses:
'200':
description: echo response
content:
text/plain:
schema:
type: integer # <1>
format: year
<1>带有自定义format的整数类型。
默认情况下，OpenAPI-Processor-spring不知道该如何处理自定义格式，只需将OpenApi integer映射到Java Integer。
生成的接口代码
package io.openapiprocessor.oap.api;
import io.openapiprocessor.oap.support.Generated;
import javax.validation.constraints.NotNull;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
@Generated(value = "openapi-processor-spring", version = "2023.2")
public interface Api {
/**
* echo query parameter with type mapping
*
* @return echo response
*/
@GetMapping(
path = "/query",
produces = {"text/plain"})
Integer getQuery(@RequestParam(name = "year") @NotNull Integer year);
}
由于Java具有java.time.Year类，因此使用它而不是Integer。
我们可以轻松地帮助OpenAPI-Processor通过将A type映射添加到mapping.yaml Configuration。
映射.yaml
openapi-processor-mapping: v3
options:
generated-date: false
package-name: io.openapiprocessor.oap
bean-validation: javax
javadoc: true
map:
types:
- type: integer:year => java.time.Year # <1>
<1>这是mapping.yaml的有趣部分。它告诉处理器将整数自定义格式映射到java.time.Year类。
箭头的左侧是type：openapi中使用的format组合，在右侧是生成代码中使用的完全合格的Java类名称。
再生代码现在将生成这样的接口：
生成的接口代码
package io.openapiprocessor.oap.api;
import io.openapiprocessor.oap.support.Generated;
import java.time.Year;
import javax.validation.constraints.NotNull;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
@Generated(value = "openapi-processor-spring", version = "2023.2")
public interface Api {
/**
* echo query parameter with type mapping
*
* @return echo response
*/
@GetMapping(
path = "/query",
produces = {"text/plain"})
Year getQuery(@RequestParam(name = "year") @NotNull Year year); // <1>
}
<1>现在使用java.time.Year而不是Integer。
简单： - ）
如果在OpenAPI模式的属性中使用了这种自定义类型，则OpenAPI-Processor将使用相同的类型映射定义。
我们可以使用这种简单的机制来改善生成的代码，例如：
类型映射示例
- type: string:uuid => java.util.UUID
- type: string:date-time => java.time.Instant
- type: string:offset-date-time => java.time.OffsetDateTime
我确定您可以找到更多有用的映射。 ： - ）
感谢您的阅读！
摘要
这篇简短的文章描述了使用类型映射改善OpenAPI-Poeressor生成的代码非常容易。
有关更多信息，请参见documentation。