You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
****{source type}** is the type name used in the OpenAPI description and names the type that should
28
-
receive the additional annotation.
27
+
****{source type}** is the type name used in the OpenAPI description and names the type that should receive the additional annotation. This can be a **{type}:{format}** combination like `string:uuid`.
29
28
30
29
****{annotation type}** is the fully qualified class name of the java annotation type. It may have parameters (see example below).
31
30
32
31
The link:{oap-samples}[samples project] has a small example using annotation mappings similar to the one described below.
33
32
33
+
== combining annotation mapping and type mapping
34
+
35
+
[.badge .badge-since]+since 2023.1+
36
+
37
+
Previously an annotation mapping was lost if the type was mapped at the same time to an existing class. It will now add the annotation to the existing class if possible.
38
+
39
+
Assume the following mapping:
40
+
41
+
[source,yaml]
42
+
----
43
+
openapi-processor-mapping: v3
44
+
45
+
options:
46
+
47
+
map:
48
+
types:
49
+
- type: Foo => openapiprocessor.MappedFoo
50
+
- type: Foo @ annotation.Bar # <1>
51
+
52
+
parameters:
53
+
- type: Foo @ annotation.Bar # <2>
54
+
----
55
+
56
+
`MappedFoo` is a class that is not generated. Adding an annotation at the parameter level works as expected (mapping `<2>`). But it is not possible to add the `Bar` annotation directly at the class (mapping `<1>`) like it is possible on a generated class:
57
+
58
+
[source,java]
59
+
----
60
+
@Bar
61
+
@Generated
62
+
public class Foo {
63
+
// ....
64
+
}
65
+
----
66
+
67
+
instead, openapi-processor will add it on any `MappedFoo` property used in the generated model classes:
68
+
69
+
[source,java]
70
+
----
71
+
@Generated
72
+
public class FooBar {
73
+
74
+
@Bar
75
+
@JsonProperty("foo")
76
+
private MappedFoo foo;
77
+
78
+
// ....
79
+
}
80
+
----
81
+
82
+
34
83
== mapping example
35
84
36
85
Given the following OpenAPI description, that describe two (echo like) endpoints that receive an object via post and return the same object. In the mapping file we add a custom bean validation annotation. It checks the sum of both properties in `Foo` and `Bar`.
@@ -132,7 +181,7 @@ map:
132
181
133
182
The `Sum` annotation in the example is a custom bean validation but the feature itself is not limited to bean validation.
134
183
135
-
<1> use `v2.1` as the mapping version to avoid validation warnings in the mapping file.
184
+
<1> use `v2.1` (or later) as the mapping version to avoid validation warnings in the mapping file.
136
185
<2> the `Bar` mapping is using a global type annotation mapping, so the annotation is added to the generated `Bar` class.
137
186
<3> the `Foo` mapping adds the annotation to the parameter of the endpoint methods that use `Foo`.
138
187
<4> this is a list of examples that shows annotation parameters.
Copy file name to clipboardExpand all lines: docs/modules/ROOT/pages/mapping/structure.adoc
+20-17Lines changed: 20 additions & 17 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,33 +1,30 @@
1
1
= type mapping structure
2
2
include::partial$links.adoc[]
3
3
4
-
The type mapping is part of the mapping yaml (see xref:processor/configuration.adoc[Configuration])
5
-
and configured under the `map` key. The `map` key contains multiple sections to define the different
6
-
kinds of type mappings.
4
+
The type mapping is part of the mapping yaml (see xref:processor/configuration.adoc[Configuration]) and configured under the `map` key. The `map` key contains multiple sections to define the different kinds of type mappings.
7
5
8
6
All sections are optional.
9
7
10
-
== type mapping structure (v2)
8
+
== type mapping structure
11
9
12
10
//[.badge .badge-since]+since 1.0.0.M15+
13
11
14
-
This is the preferred format for the mapping. It is simpler than the previous format and uses fewer
15
-
keywords.
16
-
17
12
[IMPORTANT]
18
13
====
19
-
To use the new format the mapping file needs the following key on the top-level. Best place is the
20
-
first line of the `mapping.yaml` file.
14
+
The mapping file needs the following key on the top-level. Best place is the first line of the `mapping.yaml` file.
21
15
22
16
[source,yaml]
23
17
----
24
-
openapi-processor-mapping: v2
18
+
openapi-processor-mapping: v3
25
19
----
26
20
====
27
21
22
+
The version increases from time to time when openapi-processor requires a new or changed configuration. In case the version changes it is mentioned in the release notes.
23
+
28
24
29
-
To map a source type to a destination type it is using an `=>` arrow as *mapping operator* instead
30
-
of individual keywords:
25
+
=== basic mapping
26
+
27
+
To map a source type to a destination type it is using an `=>` arrow as *mapping operator* instead of individual keywords:
The full structure of the mapping looks like this (a real mapping file will usually use just a few of the possible keys):
40
39
41
40
[source,yaml]
@@ -56,8 +55,12 @@ map:
56
55
57
56
# list of global mappings
58
57
types:
58
+
# replace source type with the given target type
59
59
- type: {source type} => {target type}
60
60
61
+
# add an extra annotation to the source type
62
+
- type: {source type} @ {target type}
63
+
61
64
# list of global parameter mappings
62
65
parameters:
63
66
- name: {parameter name} => {target type}
@@ -94,8 +97,12 @@ map:
94
97
95
98
# list of path specific mappings
96
99
types:
100
+
# replace source type with the given target type
97
101
- from: {source type} => {target type}
98
102
103
+
# add an extra annotation to the source type
104
+
- type: {source type} @ {target type}
105
+
99
106
# list of path specific parameter mappings
100
107
parameters:
101
108
- name: {parameter name} => {target type}
@@ -124,8 +131,4 @@ The structure below `paths` is similar to an OpenAPI yaml file to make it easier
124
131
125
132
== json schema
126
133
127
-
Some IDEs support json schemas to provide editing support (auto completion & validation) for text based files. To support this openapi-processor has a link:{json-schema}[json schema] for the v2 mapping format.
128
-
129
-
== type mapping structure (v1)
130
-
131
-
This format of the mapping ist still available but should not be used anymore.
134
+
Some IDEs support json schemas to provide editing support (auto-completion & validation) for text based files. To support this, openapi-processor provides json schemas for the mapping formats at link:{json-schema-site}[`https://openapiprocessor.io/schemas/mapping/mapping-v{version}.json`].
Copy file name to clipboardExpand all lines: docs/modules/ROOT/pages/processor/configuration.adoc
+12-10Lines changed: 12 additions & 10 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -8,13 +8,13 @@ A mapping yaml looks like this:
8
8
9
9
[source,yaml]
10
10
----
11
-
openapi-processor-mapping: v2
11
+
openapi-processor-mapping: v3
12
12
13
13
options:
14
14
package-name: io.openapiprocessor.sample
15
15
model-name-suffix: Resource
16
16
one-of-interface: true
17
-
bean-validation: true
17
+
bean-validation: jakarta
18
18
generated-date: true
19
19
format-code: false
20
20
javadoc: true
@@ -23,12 +23,11 @@ map:
23
23
# java type mappings
24
24
----
25
25
26
-
The only required option is `package-name`.All other options or the type mappings are optional.
26
+
The only required option is `package-name`.All other options or the type mappings are optional.
27
27
28
28
== options:
29
29
30
-
* `package-name`: (**required**) the root package name of the generated interfaces & models.The
31
-
package folder tree will be created inside the `targetDir` (see xref:gradle.adoc[using gradle]).
30
+
* `package-name`: (**required**) the root package name of the generated interfaces & models.The package folder tree will be created inside the `targetDir` (see xref:gradle.adoc[using gradle]).
32
31
+
33
32
Interfaces and models will be generated into the `api` and `model` subpackages of `package-name`.
34
33
+
@@ -37,8 +36,14 @@ Interfaces and models will be generated into the `api` and `model` subpackages o
37
36
38
37
* `model-suffix-name` (**optional**, default is empty). See xref:_model_name_suffix[below].
39
38
40
-
* `bean-validation` (**optional**, `true` or `false`) enables generation of bean validation
41
-
annotations. Default is `false`. See link:{bean-validation}[Bean Validation Specification, window="_blank"].
39
+
* `bean-validation` (**optional**, `true` or `false`, `javax`, `jakarta`) enables generation of bean validation annotations. Default is `false`. See link:{bean-validation}[Bean Validation Specification, window="_blank"].
40
+
+
41
+
With the [.badge .badge-since]+2023.1+ releases this key allows two new values to handle the package name change from bean validation v2 to v3 (`javax` => `jakarta`).
42
+
43
+
** `false`: disables bean validation annotations
44
+
** `true`: enables bean validation annotations v2, with `javax` package name
45
+
** `javax`: enables bean validation annotations v2, with `javax` package name
46
+
** `jakarta`: enables bean validation annotations v3, with `jakarta` package name
42
47
43
48
* `javadoc` (**optional**, `true` or `false`) enables generation of JavaDoc comments from the OpenAPI `description` s on the API interfaces and model pojos.Default is `false`.This is still experimental.
44
49
@@ -141,9 +146,6 @@ public class BarResource { // <4>
141
146
<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`.
142
147
143
148
144
-
145
-
146
-
147
149
== map:
148
150
149
151
Using type mapping we can tell the processor to map types (schemas) from an `openapi.yaml`
0 commit comments