Configuration
The processor reads the configuration from the (mandatory) mapping.yaml
file.It does contain
some general options and the mapping type information.
A mapping yaml looks like this:
openapi-processor-mapping: v9
options:
package-name: io.openapiprocessor.sample
model-name-suffix: Resource
model-type: record
enum-type: string
one-of-interface: true
bean-validation: jakarta
generated: true
generated-date: true
format-code: true
javadoc: true
clear-target-dir: false
json-property-annotation: always
target-dir:
layout: standard
base-path:
server-url: 0
properties-name: api.properties
compatibility:
bean-validation-valid-on-reactive: false
identifier-word-break-from-digit-to-letter: false
map:
# java type mappings
The only required option is package-name
. All other options or the type mappings are optional.
options:
package-name
required (string)
the root (java) package name of the generated interfaces & models.The package folder tree will be created inside the targetDir
(see using gradle).
Interfaces and models will be generated into the api
and model
subpackages of package-name
.
-
the final package name of the generated interfaces will be
"${package-name}.api"
, -
and the final package name of the generated models will be
"${package-name}.model"
model-name-suffix
optional (string, default is empty (i.e. it is disabled))
The model-name-suffix
option sets a suffix that is automatically appended to all generated model and enum classes.
The suffix helps to
-
avoid duplicate class names in generated code and normal code
-
makes it easier to recognize which role or in which context a class is used. Is it a data transfer class or is it a domain class?
-
keeps the suffix "noise" out of the OpenAPI description
Usually you will separate the classes by putting them in different packages. This helps to distinguish the classes, but when both are used in the same code, i.e. when converting one format to the other, it is a lot easier to distinguish them by their class name instead of their package name.
If a schema name from the OpenAPI description already ends with the model-name-suffix
, the processor will not append the suffix. This allows to migrate an existing api with a suffix in the API to model-name-suffix
step by step.
example
OpenAPI
paths:
/foo:
get:
responses:
'200':
description: the foo result
content:
application/json:
schema:
$ref: '#/components/schemas/Foo' (1)
components:
schemas:
Foo:
type: object
properties:
nested:
$ref: '#/components/schemas/BarResource' (1)
BarResource:
type: object
properties:
prop:
type: string
mapping.yaml
openapi-processor-mapping: v8
options:
package-name: io.openapiprocessor.sample
model-name-suffix: Resource (2)
Java
// interface
public interface Api {
@Mapping("/foo")
FooResource getFoo(); (3)
}
// pojos
public class FooResource { (3)
// ...
@JsonProperty("nested")
private BarResource nested;
// ...
}
public class BarResource { (4)
// ...
}
1 | a schema name without suffix |
2 | the suffix configuration |
3 | the class name of the Foo schema got the configured Resource suffix |
4 | the class name of the BarResource is identical to the original schema name. Since the existing suffix is equal to model-name-suffix it is ignored. Otherwise, This prevents funny class names like BarResourceResource . |
model-type
optional* (string, default
or record
, default is default
)
generate pojos (class with get/set property methods) or records model classes from OpenAPI schemas. This is a global setting in the mapping.yaml
. It can either have the value default
(which is default) to generate pojos or record
to generate records.
example
mapping.yaml
openapi-processor-mapping: v9
options:
model-type: record
With model-type: record
the processor will generate record
s like this:
Java record
package generated.model;
import com.fasterxml.jackson.annotation.JsonProperty;
import generated.support.Generated;
@Generated(value = "openapi-processor-core", version = "test")
public record Foo(
@JsonProperty("bar")
String bar
) {}
and without model-type
or model-type: default
it will create a simple pojo:
Java pojo
package generated.model;
import com.fasterxml.jackson.annotation.JsonProperty;
import generated.support.Generated;
@Generated(value = "openapi-processor-core", version = "test")
public class Foo {
@JsonProperty("bar")
private String bar;
public String getBar() {
return bar;
}
public void setBar(String bar) {
this.bar = bar;
}
}
bean-validation
optional (boolean or string, true
or false
, javax
, jakarta
, default is false
)
enables generation of bean validation annotations. See Bean Validation Specification.
to handle the package name change from bean validation v2 to v3 (javax
⇒ jakarta
) it accepts the package name as an enabling value:
-
false
: disables bean validation annotations -
true
: enables bean validation annotations v2, withjavax
package name -
javax
: enables bean validation annotations v2, withjavax
package name -
jakarta
: enables bean validation annotations v3, withjakarta
package name
javadoc
optional (boolean, true
or false
, default is false
)
enables generation of JavaDoc comments from the OpenAPI description
s on the API interfaces and model pojos.
format-code
optional (boolean, true
or false
, default is false
)
enable or disable the code formatter. See also JDK 16+.
one-of-interface
optional (boolean, true
or false
, default is false
)
enables generation of marker interfaces for oneOf
objects. See oneOf marker interfaces.
generated-annotation
optional (boolean, true
or false
, default is true
)
enable or disable the @Generated
annotation.
generated-date
optional (boolean, true
or false
, default is ´true`)
enable or disable the generated date on the @Generated
annotation.
clear-target-dir
optional (boolean, true
or false
, default is true
)
enable or disable clearing of the targetDir
when the processor is writing the generated files.
See also target-dir:clear.
json-property-annotation
optional (string, always
, auto
, never
, default is always
)
control generation of the @JsonProperty
annotation:
-
always
: adds@JsonProperty
to all schema property -
auto
: adds@JsonProperty
only if it is required because the property name is no valid java identifier or the property is defined asreadOnly
/writeOnly
in the OpenAPI description -
never
: never adds@JsonProperty
to a schema property. NOTE: this may produce invalid code if the property name is not a valid java identifier.
enum type
optional* (string, default
, string
or framework
, default is default
)
There are 3 ways to handle OpenAPI enum definitions, default
, string
and framework
.
default
generates a typical java enum class.
The other two can be used if default
does not work.This is described in more detail under enums.
string
does not generate an enum and simply uses java.lang.String
.In case bean validation is enabled it will generate a custom bean validation annotation that checks if the incoming values is one of the enum
values given in the OpenAPI description.
framework
does generate a slightly different enum classes than default
and a Spring ConverterFactory
that can deserialize incoming values to proper enum values.
base-path
parent key to group base path related options. See Server Url.
base-path:server-url
optional (boolean or number, false
, true
=0, 1, 2, …, default is false
)
enables generation of a resource file with the configured OpenAPI server/url
.
To have a destination directory for generating the resource file, setting this will automatically enable the standard target dir layout.
|
base-path:properties-name
optional (string, default is api.properties
)
name of the properties resource file that will contain the base-path
configuration.
target-dir:clear
optional (boolean, true
or false
, default is true
)
overrides clear-target-dir
enable or disable clearing of the targetDir
when the processor is writing the generated files (See also clear-target-dir).
target-dir:layout
optional (string, classic
or standard
, default is classic
)
this controls if the targetDir
is the source root folder or if there is another directory level.
-
classic
,targetDir
is the source root, i.e. the package structure begins intargetDir
.targetDir \--- io \--- openapiprocessor +--- api \--- model
-
standard
,targetDir
is the parent of source root and resource root, i.e. the package structure begins in thejava
subdirectory and thejava`director has a `resources
sibling directory.targetDir +--- java | \--- io | \--- openapiprocessor | +--- api | \--- model \--- resources
compatibility:
This section contains keys to disable breaking changes.
identifier-word-break-from-digit-to-letter
optional (boolean, true
or false
, default is true
)
keep the pre-2024.2 behaviour. See Identifiers.
bean-validation-valid-on-reactive
optional (boolean, true
or false
, default is true
)
keep the pre-2024.2 behaviour. See Bean Validation.
map:
Using type mapping we can tell the processor to map types (schemas) from an openapi.yaml
description to a specific existing java type instead of generating a model class from the source
OpenAPI type.
This is one of the core features and has his own description in mapping.