Identifiers

general

The processor will map identifiers used in the OpenAPI description (i.e. yaml file) to valid Java identifiers.

The Java identifiers will use camel case, starting with an upper case letter if it is a type name and a lower case letter if it is a variable name.

Camel case will be produced by detecting word breaks on special characters and using an upper case first letter on the next word. The special characters are:

  • characters that are not allowed in java identifiers, (for example, a - (minus)). This is checked by using Character.isJavaIdentifierStart() and Character.isJavaIdentifierPart()

  • _ (underscore). The underscore is possible in java identifiers but usually not used apart from enums.

  • a change from letter to number. (see table below).

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

since 2024.2

foo2Bar

foo2Bar

foo2Bar

Foo2Bar

FOO2_BAR

before 2024.2

foo2Bar

foo2bar

foo2bar

Foo2bar

FOO2BAR

model

For properties of model classes, the properties will be annotated with @JsonProperty to provide the mapping from the OpenAPI identifier to the Java identifier.

    class Example {

        @JsonProperty("foo-bar")
        private String fooBar;

        // ...
    }

The @JsonProperty(…​) annotations are necessary in case a json property name is not a valid java identifier.

Any JSON identifier gets converted to a valid java identifier. If it differs from the JSON identifier, Spring (jackson) would be unable to correctly map the properties.

To avoid this issue, the processor adds the annotation.