Releases: openapi-processor/openapi-processor-base
2024.6.1
2024.6
(#176) 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/{api}"
variables:
path:
default: api
and a mapping
openapi-processor-mapping: v9
options:
base-path:
# false/true=0,1,2,... (default false)
server-url: true
it will generate a properties file api.properties
openapi.base.path = /api
that can be used to configure the (Spring) context-path
:
# application.properties
#spring.config.import = api.properties
server.servlet.context-path=${openapi.base.path}
Take a look at the documentation for more details.
(openapi-processor/openapi-processor-spring#288) 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
) {}
(openapi-processor/openapi-processor-spring#287) 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.
(#158) type annotation mapping ignored with model-name-suffix
using a mapping like this:
openapi-processor-mapping: v9
options:
model-name-suffix: Resource
maps:
types:
- type: Foo @ io.openapiprocessor.Annotation()
did not add the annotation because of the model-name-suffix
.
dependency updates
- updated (internal) OpenAPI parser to 2024.4 (was 2024.3)
- updated com.fasterxml.jackson:jackson-bom from 2.17.1 to 2.17.2
- updated com.google.googlejavaformat:google-java-format from 1.22.0 to 1.23.0
2024.5
(#156) 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
...
(#152) missing @Generated
the generated Values
and ValueValidator
(used by enum-type
string
) were not annotated with @Generated
.
(openapi-processor/openapi-processor-spring#271) (fix) 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.
(openapi-processor/openapi-processor-spring#269) 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: false
(openapi-processor/openapi-processor-spring#268) control @JsonProperty
annotation
By setting the json-property-annotation
option is is possible to control the generation of the @JsonProperty annotation. It allows thre values: always
, auto
or never
.
always
: (the default) adds a@JsonProperty
annotation to all properties.auto
: only adds a@JsonProperty
annotation 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@JsonProperty
annotation 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: auto
2024.4
(openapi-processor/openapi-processor-spring#262) (fix) 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.
(#145) (fix) 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");
...
}
(#143) (fix) 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.JsonNullable
on a property
properties:
bar:
nullable: true
type: string
maxLength: 4
did not add the constraint to the generated property.
dependency updates
- updated (internal) OpenAPI parser to 2024.3 (was 2024.2)
- updated swagger parser to 2.1.22 (was 2.1.21)
2024.3
(#130) (fix) setting the new compatibility options did not work
setting the new compatibility options did not work, it was always using the default values.
(#129) remove extra line feed in javadoc
removed the extra line feed (an empty line) in javadoc comments between summary and description.
(#123) optionally clear output directory
its is now possible to disable clearing of the targetDir
when the processor is writing the generated files.
openapi-processor-mapping: v7
options:
# ...
# enable/disable deletion of targetDir: true (default) or false.
clear-target-dir: false
2024.2
(#92) (new) 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
- listB
we 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;
}
}
(new) 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.Foo
(breaking) (openapi-processor/openapi-processor-spring/issues/229) reactive 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: false
I 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.
(breaking) 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 |
keeping the old behavior
To postpone the update, set the identifier-word-break-from-digit-to-letter
option to false
.
openapi-processor-mapping: v6
options:
# ...
compatibility:
# optional, default is true
identifier-word-break-from-digit-to-letter: false
(openapi-processor/openapi-processor-spring#239) Support Mono as result type by @maddingo
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.Flux
Using 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.Flux
which 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.
2024.1
re-released as 2024.2
not used.
(#92) (new) 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
- listB
we 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;
}
}
(new) 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.Foo
(may be breaking) (openapi-processor/openapi-processor-spring/issues/229) reactive 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.
To postpone the update, set the bean-validation-valid-on-reactive
option to false
.
openapi-processor-mapping: v6
options:
bean-validation: jakarta
# default is true
bean-validation-valid-on-reactive: false
I 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.
2023.6.1
(#91) (fix) nested objects were not generated for generic types
having a mapping like this
map:
types:
- type: Values => java.util.Map<java.lang.String, {package-name}.model.Value>>
the processor did not generate nested object classes of Value
.
It is now checking the generic type for nested objects and generates the required object classes.
2023.6
(new) support different enum styles
it is now possible to (globally) configure different enum types in mapping.yaml
:
openapi-processor-mapping: v5
options:
package-name: generated
enum-type: default|string|framework
default
, which is default, creates a simple java enum with all uppercase enum values. It will create the same code as previous versions.
string
, simply uses String
and does not create an enum class. This is useful if automatic conversion of the incoming value to a java enum value does not work. In case bean-validation
is enabled the processor adds a (generated) validation annotation that verifies that the string is a valid (OpenAPI) enum value.
public interface FooApi {
@Mapping(path = "/foo", produces = {"application/json"})
Foo postFoo(@Parameter(name = "enum") @Values(values = {"one", "two"}) String aEnum);
}
framework
, is a placeholder for framework specific enum generation, only supported by openapi-processor-spring.
2023.5
#59 (new) support primitive types
it is now possible to use primitive types in mapping.yaml
:
openapi-processor-mapping: v4
options:
package-name: generated
map:
types:
- type: string:binary => byte[]
dependency updates
- updated (internal) OpenAPI parser to 2023.5 (was 2023.4)
- updated swagger parser to 2.1.18 (was 2.1.16)