2022 Releases
October 2022
-
openapi-processor-spring/micronaut 2022.5
annotation mapping
this is a new feature.
It allows to place additional annotations on generated model classes. It is possible to place the annotation at the class itself or on parameters of that type.
openapi-processor-mapping: v2.1 (1)
options:
package-name: io.openapiprocessor.openapi
bean-validation: true
map:
types:
- type: Bar @ io.openapiprocessor.samples.validations.Sum(24) (2)
parameters:
- type: Foo @ io.openapiprocessor.samples.validations.Sum(value = 42) (3)The Sum annotation in the example is a custom bean validation but the feature itself is not limited to bean validation.
| 1 | use v2.1 as the mapping version to avoid validation warnings in the mapping file. |
| 2 | the Bar mapping is using a global type annotation mapping, so the annotation is added to the generated Bar class. |
| 3 | the Foo mapping adds the annotation to the parameter of the endpoint methods that use Foo. |
See annotation mapping for the details.
@Generated
This will replace the text header from the generated files with a (generated) @Generated annotation.
Other tools may be able to detect the generated files and ignore them.
For example jacoco automatically ignores @Generated classes. It is no longer necessary to exclude the generated files from code coverage.
A generated interface/class will now look like this:
package io.openapiprocessor.release;
import io.openapiprocessor.release.support.Generated;
import org.springframework.web.bind.annotation.GetMapping;
@Generated(value = "openapi-processor-spring", version = "2022.6", date = "2022-09-28T18:37:33.250622+02:00")
public interface ReleaseApi {
// ...
}Because of the longish date the code formatter will probably add a few line breaks.
Generation of the data parameter can be disabled by setting the generated-date option to false:
openapi-processor-mapping: v2.1 (1)
options:
package-name: io.openapiprocessor.openapi
generated-date: false| 1 | use v2.1 as the mapping version to avoid validation warnings in the mapping file. |
additional parameter configuration did not working in global context
using an additional parameter in the global context was not implemented.
map:
parameters:
- add: request => javax.servlet.http.HttpServletRequestMay 2022
-
openapi-processor-spring/micronaut 2022.4
openapi-processor offers a new alternative OpenAPI 3.0 & 3.1 parser and fixes missing bean validation imports
-
OpenAPI 3.0 support includes JSON schema validation with detailed reporting.
-
OpenAPI 3.1 support is experimental and does not yet support schema validation.
OpenAPI 3.0 parser & JSON schema validation
openapi-processor provides an alternative internal OpenAPI 3.0 parser. It includes JSON schema validation with detailed reporting.
To enable it, set the parser configuration to INTERNAL.
// build.gradle processor configuration
openapiProcessor {
spring {
processor 'io.openapiprocessor:openapi-processor-spring:2022.4'
apiPath "${projectDir}/src/api/openapi.yaml"
targetDir "$projectDir/build/openapi"
mapping "${projectDir}/src/api/mapping.yaml"
// use internal OpenAPI parser
parser 'INTERNAL'
}
}OpenAPI 3.1 (experimental)
The internal OpenAPI parser supports OpenAPI 3.1 but does not yet have schema validation.
To enable it, set the parser configuration to INTERNAL. It will automatically detect OpenAPI 3.0 & 3.1.
The processor does handle the renamed/changed OpenAPI 3.1 properties as needed for code generation:
type keyword
The type keyword allows a list of types. Defining a nullable type is done by adding "null" to the list of types.
# OpenAPI v3.0
type: string
nullable: true
# OpenAPI v3.1
type:
- "string"
- "null"The processor does support the new nullable definition. Apart from that it will use the first non-null type as the type for code generation.
exclusiveMinimum and exclusiveMaximum keywords
# OpenAPI v3.0
maximum: 42
exclusiveMaximum: true
# OpenAPI v3.1
exclusiveMaximum: 42which is used for adding bean validations.
missing import for javax.validation.constraints.Pattern
the `import`s for bean validation annotations were missing for item constraints of a mapped array. Having an api description like this
paths:
/test:
get:
parameters:
- in: query
name: patternParam
required: false
description: query parameter with @Pattern annotation
schema:
$ref: '#/components/schemas/PatternParam'
responses:
'200':
description: ok
schemas:
PatternParam:
type: array
items:
type: string
pattern: '.*'and a mapping
openapi-processor-spring: v2
options:
package-name: generated
bean-validation: true
map:
types:
- type: array => java.util.Listdid not generate the javax.validation.constraints.Pattern import.
package generated.api;
import annotation.Mapping;
import annotation.Parameter;
import java.util.List;
import javax.validation.constraints.Pattern;
public interface Api {
@Mapping("/test")
void getTest(@Parameter List<@Pattern(regexp = ".*") String> patternParam);
}(ignore the @Mapping/@Parameter annotations, this is pseudo-code used by the integration tests)