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
A simple path of the OpenAPI description will usually produce a single endpoint method in the target
4
-
interface as described in the introduction.
3
+
A simple path of the OpenAPI description will usually produce a single endpoint method in the target interface as described in the introduction.
5
4
6
-
OpenAPI allows us to define more complex apis that behave differently based on the request header.
7
-
For example the following api definition can return its response in different formats.As json or as
8
-
plain text:
5
+
OpenAPI allows us to define more complex apis that behave differently based on the request header. For example the following api definition can return its response in different formats. As json or as plain text:
9
6
10
7
[source,yaml]
11
8
----
12
-
openapi: 3.0.2
9
+
openapi: 3.1.0
13
10
info:
14
11
title: multiple response content types
15
12
version: 1.0.0
@@ -50,11 +47,9 @@ components:
50
47
type: string
51
48
----
52
49
53
-
A client request uses the request `Accept` header to tell the api which result content types it can
54
-
handle.
50
+
A client request uses the request `Accept` header to tell the api which result content types it can handle.
55
51
56
-
Using a single endpoint method it has to decide which response to create.This leads to some boring
57
-
`if/else` code.To avoid this the processor creates one endpoint method for each possible response.
52
+
Using a single endpoint method it has to decide which response to create.This leads to some boring `if/else` code. To avoid this the processor creates one endpoint method for each possible response.
58
53
59
54
== multiple content types
60
55
@@ -82,11 +77,9 @@ public interface Api {
82
77
}
83
78
----
84
79
85
-
The apis normal response (status '200') can return the result as json or as plain text which leads
86
-
to two methods for the same endpoint but with a different `produces` list in the mapping annotation.
80
+
The apis normal response (status '200') can return the result as json or as plain text which leads to two methods for the same endpoint but with a different `produces` list in the mapping annotation.
87
81
88
-
One method when json gets requested and one when plain text gets requested.Spring will take care of
89
-
selecting the correct endpoint.
82
+
One method when json gets requested and one when plain text gets requested. Spring will take care of selecting the correct endpoint.
90
83
91
84
[#result_style]
92
85
== multiple content types & default content type
@@ -103,13 +96,13 @@ With version *2021.5* it is possible to generate the endpoints with the success
103
96
104
97
Since it is common practice to handle errors by throwing exceptions (e.g. in combination with the Spring `@ResponseStatus` annotation) the endpoint methods don't need to handle different return types, and it is possible to simply use the type of the success response.
105
98
106
-
To switch between previous and new behavior there is a new mapping configuration to control the style of the return type named `result-style`.It has two possible values: `success` or `all`.This is currently a global mapping switch.
99
+
To switch between previous and new behavior there is a new mapping configuration to control the style of the return type named `result-style`.It has two possible values: `success` or `all`.This is available on all mapping levels (([.badge .badge-since]+new with 2025.2+)).
107
100
108
-
The default is `success`, i.e. the processor will automatically generate the code using the new behavior.In case the previous behavior is required set the `result-style` to `all`.
101
+
The default is `success`, i.e. the processor will automatically generate the code using the new behavior.In case the previous behavior is required, set the `result-style` to `all`.
109
102
110
103
[source,yaml]
111
104
----
112
-
openapi-processor-mapping: v8
105
+
openapi-processor-mapping: v12
113
106
114
107
options:
115
108
package-name: ...
@@ -121,7 +114,7 @@ map:
121
114
122
115
**new behavior, since 2021.5**
123
116
124
-
Example of the new code, using `result-style: success`.This is the default if `result-style` is not set.
117
+
Example of the new code, using `result-style: success`.This is the default if `result-style` is not set.
125
118
126
119
[source,java]
127
120
----
@@ -171,6 +164,160 @@ public interface Api {
171
164
}
172
165
----
173
166
167
+
== multiple responses with same content type
168
+
169
+
[.badge .badge-since]+new with 2025.2+
170
+
171
+
There is a case that was not properly handled before: if an endpoint of the OpenAPI description has multiple success responses with the same content type (e.g. `application/json`) but different response payloads.
172
+
173
+
The processor did honor only one response status using the _last_ success response.
174
+
175
+
Here is an example OpenAPI:
176
+
177
+
[source, yaml]
178
+
----
179
+
openapi: 3.1.0
180
+
info:
181
+
title: test multiple success responses
182
+
version: 1.0.0
183
+
184
+
paths:
185
+
/foo:
186
+
get:
187
+
description: endpoint with multiple success responses
188
+
responses:
189
+
'200':
190
+
description: success
191
+
content:
192
+
application/json:
193
+
schema:
194
+
$ref: '#/components/schemas/Foo'
195
+
'202':
196
+
description: another success
197
+
content:
198
+
application/json:
199
+
schema:
200
+
$ref: '#/components/schemas/Bar'
201
+
202
+
components:
203
+
schemas:
204
+
205
+
Foo:
206
+
type: object
207
+
properties:
208
+
foo:
209
+
type: string
210
+
211
+
Bar:
212
+
type: object
213
+
properties:
214
+
bar:
215
+
type: string
216
+
----
217
+
218
+
The two result payloads `Foo` and `Bar` are handled by two possible ways now.
219
+
220
+
Either by using `Object` as return type or by generating a marker interface that's implemented by both payload and using it as the result type.
221
+
222
+
=== using `Object` as the result type
223
+
224
+
This is the default. To return either `Foo` or `Bar` from the endpoint method it uses `Object` as the return type.
225
+
226
+
[source,java]
227
+
----
228
+
package generated.api;
229
+
230
+
import annotation.Mapping;
231
+
import generated.support.Generated;
232
+
233
+
@Generated(value = "openapi-processor-core", version = "test")
234
+
public interface Api {
235
+
236
+
@Mapping("/foo")
237
+
Object getFooApplicationJson();
238
+
239
+
}
240
+
241
+
----
242
+
243
+
=== using a marker interface as result type
244
+
245
+
An `Object` return type is obviously not very descriptive. It is impossible to know from the interface which results are possible.
246
+
247
+
To improve on that situation the processor can generate a marker interface that is more descriptive and helps with navigation in the IDE.
248
+
249
+
Generation of the marker interface is enabled by adding the `response-interface` option:
@Generated(value = "openapi-processor-core", version = "test")
308
+
public class Foo implements GetFooApplicationJsonResponse {
309
+
310
+
@JsonProperty("foo")
311
+
private String foo;
312
+
313
+
// ...
314
+
}
315
+
316
+
----
317
+
318
+
If the response type (`Foo` in this case) is used on multiple endpoints with multiple success response status it will implement multiple marker interfaces.
319
+
320
+
In case one of the success responses is a primitive result (like `String`) the processor will fall back to using `Object` because it can't hide the primitive type behind a marker interface.
174
321
175
322
== multiple content types, default content type & result wrapper
176
323
@@ -206,5 +353,4 @@ public interface Api {
206
353
}
207
354
----
208
355
209
-
The response wraps the type by a `ResponseEntity` and to handle the multiple response types the
210
-
generic parameter is the *unknown* type.
356
+
The response wraps the type by a `ResponseEntity` and to handle the multiple response types the generic parameter is the *unknown* type.
0 commit comments