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: v3
options:
package-name: io.openapiprocessor.sample
model-name-suffix: Resource
one-of-interface: true
bean-validation: jakarta
generated-date: true
format-code: false
javadoc: true
map:
# java type mappings
The only required option is package-name
. All other options or the type mappings are optional.
options:
-
package-name
: (required) the root package name of the generated interfaces & models.The package folder tree will be created inside thetargetDir
(see using gradle).Interfaces and models will be generated into the
api
andmodel
subpackages ofpackage-name
.-
so 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-suffix-name
(optional, default is empty). See below. -
bean-validation
(optional,true
orfalse
,javax
,jakarta
) enables generation of bean validation annotations. Default isfalse
. See Bean Validation Specification.With the 2023.1 releases this key allows two new values to handle the package name change from bean validation v2 to v3 (
javax
⇒jakarta
).-
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,true
orfalse
) enables generation of JavaDoc comments from the OpenAPIdescription
s on the API interfaces and model pojos.Default isfalse
.This is still experimental. -
format-code
(optional,true
orfalse
) enable or disable the code formatter: Default istrue
. -
one-of-interface
(optional,true
orfalse
) enables generation of marker interfaces foroneOf
objects. See oneOf marker interfaces. -
generated-date
(optional,true
orfalse
). enable or disable the generated date on the@Genearted
annotation. Default istrue
.
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: v2
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 . |
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.