2024 Releases
November 2024
-
openapi-processor-spring/micronaut 2024.6
trace mapping lookup
the processor can now create a log of the mapping lookup. It may help to understand failing mappings.
It adds two new options to control the logging.
openapi-processor-mapping: v10
options:
package-name: # ...
map:
# ...
logging:
mapping: true
mapping-target: stdoutlogging.mapping enables the logging of the mapping lookups. mapping-target set the output channel. Simplest is to use stdout. The other possible value is logger. See the logging documentation for a more detailed description.
October 2024
-
openapi-processor-spring/micronaut 2024.5
support for servers/server/url
it is now possible to tell the processor to generate a properties resource file with the path of a selected OpenAPI servers/server/url.
Given an OpenAPI description with a servers key:
openapi: 3.1.0
info:
title: server url example
version: 1.0.0
servers:
- url: "https://openapiprocessor.io/{path}"
variables:
path:
default: api
# ...and a mapping
openapi-processor-mapping: v9
options:
base-path:
# false/true=0,1,2,... (default false)
server-url: trueit will generate a properties file api.properties
openapi.base.path = /apithat can be used to configure the (Spring) context-path:
# application.properties
#spring.config.import = api.properties
server.servlet.context-path=${openapi.base.path}See Server Url for more.
javadoc of record
a record should have its javadoc at the record using @param s to describe the record properties.
Instead of
/**
* this is the <em>Foo</em> schema description
*/
@Generated(value = "openapi-processor-core", version = "test")
public record Foo(
/**
* <em>property</em> description
*/
@JsonProperty("foo-bar")
String fooBar
) {}the processor now generates:
/**
* this is the <em>Foo</em> schema description
*
* @param fooBar <em>property</em> description
*/
@Generated(value = "openapi-processor-core", version = "test")
public record Foo(
@JsonProperty("foo-bar")
String fooBar
) {}warn on endpoint without success response
the processor ignores endpoints that have no success response (i.e. 2xx response code). To detect this "error" at compile time the processor will now print a warning with the effected endpoint.
June 2024
-
openapi-processor-spring/micronaut 2024.4
add request body description to javadoc
The request body description is added as @param to the generated javadoc.
openapi: 3.1.0
info:
title: javadoc
version: v1
paths:
/foo:
get:
requestBody:
description: this is the request body
# ...missing @Generated
the generated Values and ValueValidator (used by enum-type string) were not annotated with @Generated.
missing import of class annotation parameter
using a .class parameter in a class annotation mapping did not add the import of the parameter class.
map:
types:
- type: Foo @ io.oap.ClassAnnotation(value = io.oap.Param.class)In this example the import for Param was missing.
disable @Generated
its is now possible to disable the @Generated annotation. If it is disabled the processor will not add it to any generated type.
openapi-processor-mapping: v8
options:
# ...
# enable/disable generated annotation, true (default) or false.
generated-annotation: falsecontrol @JsonProperty annotation
By setting the json-property-annotation option is is possible to control the generation of the @JsonProperty annotation. It allows three values: always, auto or never.
-
always: (the default) adds a@JsonPropertyannotation to all properties. -
auto: only adds a@JsonPropertyannotation to a property if it is required, i.e. if the OpenAPI property name is not a valid java identifier or if a property uses thereadOnly/writeOnly(OpenAPI) flags. -
never: never adds a@JsonPropertyannotation to the properties. This may generated invalid code if the property name is not a valid java identifier.
openapi-processor-mapping: v8
options:
# ...
# control @JsonProperty annotation, always (default), auto, never.
json-property-annotation: autoMay 2024
-
openapi-processor-spring/micronaut 2024.3
response $ref did not work
using responses with `$ref`s did not work with all (supported) OpenAPI parsers.
-
internal OpenAPI parser did not work (the default parser).
-
openapi4j did not work (not maintained anymore).
-
Swagger parser worked.
It now works for all 3 (supported) OpenAPI parsers.
bad enum creation
the processor did not create a proper enum for an enum description like this:
components:
schemas:
AnEnum:
type: string
enum:
- "1"
- "2"because 1 and 2 are not valid java identifiers, the processor generated
public enum Enum {
INVALID("1"),
INVALID("2");
...
}The processor will now prefix invalid identifiers with "v" (value) to avoid this. The enum above will produce
public enum Enum {
V1("1"),
V2("2");
...
}missing constraints with null mapping
using a null mapping:
openapi-processor-mapping: v7
options:
bean-validation: true
map:
paths:
/foo:
null: org.openapitools.jackson.nullable.JsonNullableon a property
properties:
bar:
nullable: true
type: string
maxLength: 4did not add the constraint to the generated property.
April 2024
-
openapi-processor-spring/micronaut 2024.2
setting the new compatibility options did not work
fixed setting the new compatibility options, it was always using the default values.
February 2024
-
openapi-processor-spring/micronaut 2024.1
annotation mapping by OpenAPI extensions
it is now possible to use OpenAPI `x-`tensions to add additional annotations to schema properties:
Here is a simple schema that has x-`tensions on the `bar property.
openapi: 3.1.0
# ...
components:
schemas:
Foo:
type: object
properties:
bar:
type: string
x-foo: single
x-bar:
- listA
- listBwe can now map the `x-`tensions/values to annotations like this:
openapi-processor-mapping: v6
map:
extensions:
x-foo: single @ io.oap.FooA(value = "any")
x-bar:
- listA @ io.oap.FooB
- listB @ io.oap.FooC-
which will generate the additional annotations on the property:
package generated.model;
import com.fasterxml.jackson.annotation.JsonProperty;
import generated.support.Generated;
import io.oap.FooA;
import io.oap.FooB;
import io.oap.FooC;
@Generated(value = "openapi-processor-core", version = "test")
public class Foo {
@FooA(value = "any")
@FooB
@FooC
@JsonProperty("bar")
private String bar;
public String getBar() {
return bar;
}
public void setBar(String bar) {
this.bar = bar;
}
}annotation mapping by parameter name
another small improvement to annotation mapping is that we can add annotations by parameter name:
openapi-processor-mapping: v6
map:
parameters:
- name: foo @ annotation.Fooreactive bean validation
the position of the @Valid annotation on reactive types has changed.
Until now the @Valid was placed on the generic type of the reactive wrapper, like this:
@Mapping("/foo-flux")
void postFooFlux(@Parameter Flux<@Valid Bar> body);but validation did not happen with Spring. Spring needs the @Valid on the reactive wrapper to trigger the validation. Therefore @Valid is now placed by default on the reactive wrapper:
@Mapping("/foo-flux")
void postFooFlux(@Parameter @Valid Flux<Bar> body);It should only take a bit annotation clean up on the interface implementations to adapt your code to the new @Valid position.
keeping the old behavior
To postpone the update, set the bean-validation-valid-on-reactive option to false.
openapi-processor-mapping: v6
options:
# ...
compatibility:
# optional, default is true
bean-validation-valid-on-reactive: falseI would like to remove this option in the future. If you still need the old @Valid position please create an issue to help me understand why the old @Valid position is still useful.
identifier word breaks
the processor does now recognize a change from letter to number as a word break. The improves generation of camel case identifiers.
given an identifier from the OpenAPI description, the processor would generate the following names for different kinds of identifiers:
| OpenAPI | camel case | variable | class | enum | |
|---|---|---|---|---|---|
new |
foo2Bar |
foo2Bar |
foo2Bar |
Foo2Bar |
FOO2_BAR |
old |
foo2Bar |
foo2bar |
foo2bar |
Foo2bar |
FOO2BAR |
Support Mono<ResponseEntity> as result type
previous versions allowed to configure a result wrapper (e.g. Spring ResponseEntity) and reactive types via single and multi mapping.
openapi-processor-mapping: v6
options:
# ...
map:
result: org.springframework.http.ResponseEntity
single: reactor.core.publisher.Mono
multi: reactor.core.publisher.FluxUsing both always wraps the reactive types with the result type. For example with Spring ResponseEntity (result type) and the reactor types Mono and Flux as
ResponseEntity<Mono<...>>
ResponseEntity<Flux<...>>Unfortunately if you need the reactive result to modify the http response, something like this:
// does not work
public ResponseEntity<Mono<Result>> someEndpoint() {
return someBean.getResult()
.map(r -> ResponseEntity
.ok()
.eTag(r.eTag())
.body(Mono.just(r)));
}it will not work because the final type of the statement is Mono<ResponseEntity<Mono<Result>>> and not the expected ResponseEntity<Mono<Result>>.
With this release we can fix that by setting the result mapping to
openapi-processor-mapping: v6
options:
# ...
map:
# wrap the ResponseEntity with Mono
result: reactor.core.publisher.Mono<org.springframework.http.ResponseEntity>
single: reactor.core.publisher.Mono
multi: reactor.core.publisher.Fluxwhich will generate the endpoint signature as
public Mono<ResponseEntity<Mono<Result>>> someEndpoint() {
// ...
}and the above code will now work.
It is recommended to configure this on the endpoint level if you just need this for a few endpoints.
See also Spring ResponseEntity documentation.