2024.7

(#9) 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: stdout

logging.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.

(#188) minimum/maximum and their exclusive version did not work for OpenAPI 3.1

actually that was an issue in the OpenAPI parser openapi-processor/openapi-parser#114

2024.6.1

(#176) support for servers/server/url

the base-path property file name configuration wasn't handled properly.

openapi-processor-mapping: v9
options:
  base-path:
    properties-name: openapi.properties

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 the readOnly/ 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 $refs 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.