Skip to content

Commit 042f241

Browse files
AzqueltAzquelt
committed
PathItem and PathItemOperation annotations
Allows PathItems to be defined under Components. Allows webhooks to be defined.
1 parent d927a38 commit 042f241

File tree

7 files changed

+303
-2
lines changed

7 files changed

+303
-2
lines changed

‎api/src/main/java/org/eclipse/microprofile/openapi/annotations/Components.java

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -107,6 +107,15 @@
107107
*/
108108
Callback[] callbacks() default {};
109109

110+
/**
111+
* An object to hold reusable Path Item Objects.
112+
*
113+
* @return the reusable PathItem objects.
114+
*
115+
* @since 4.0
116+
*/
117+
PathItem[] pathItems() default {};
118+
110119
/**
111120
* List of extensions to be added to the {@link org.eclipse.microprofile.openapi.models.Components Components} model
112121
* corresponding to the containing annotation.

‎api/src/main/java/org/eclipse/microprofile/openapi/annotations/OpenAPIDefinition.java

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -93,6 +93,15 @@
9393
*/
9494
ExternalDocumentation externalDocs() default @ExternalDocumentation;
9595

96+
/**
97+
* An array of webhook definitions which the API may be instructed to call using out-of-band mechanisms.
98+
*
99+
* @return the array of webhooks
100+
*
101+
* @since 4.0
102+
*/
103+
PathItem[] webhooks() default {};
104+
96105
/**
97106
* An element to hold a set of reusable objects for different aspects of the OpenAPI Specification (OAS).
98107
*

‎api/src/main/java/org/eclipse/microprofile/openapi/annotations/PathItem.java

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
/*
2+
* Copyright (c) 2024 Contributors to the Eclipse Foundation
3+
* <p>
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
* <p>
8+
* http://www.apache.org/licenses/LICENSE-2.0
9+
* <p>
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
package org.eclipse.microprofile.openapi.annotations;
17+
18+
import java.lang.annotation.Retention;
19+
import java.lang.annotation.RetentionPolicy;
20+
import java.lang.annotation.Target;
21+
22+
import org.eclipse.microprofile.openapi.annotations.extensions.Extension;
23+
import org.eclipse.microprofile.openapi.annotations.parameters.Parameter;
24+
import org.eclipse.microprofile.openapi.annotations.servers.Server;
25+
26+
/**
27+
* Describes a set of operations available on a single path.
28+
*
29+
* @since 4.0
30+
*/
31+
@Target({})
32+
@Retention(RetentionPolicy.RUNTIME)
33+
public @interface PathItem {
34+
35+
/**
36+
* The name of the Path Item object, used as the map key when the path item is used under
37+
* {@link Components#pathItems()} or {@link OpenAPIDefinition#webhooks()}
38+
*
39+
* @return the path item name
40+
*/
41+
String name();
42+
43+
/**
44+
* Reference value to a PathItem object.
45+
* <p>
46+
* This property provides a reference to an object defined elsewhere. This property and properties other than
47+
* {@link #name()} are mutually exclusive. If properties other than {@code name} are defined in addition to the
48+
* {@code ref} property then the result is undefined.
49+
*
50+
* @return reference to a callback object definition
51+
**/
52+
String ref() default "";
53+
54+
/**
55+
* The summary of the path item.
56+
*
57+
* @return the summary
58+
*/
59+
String summary() default "";
60+
61+
/**
62+
* The description of the path item.
63+
*
64+
* @return the description
65+
*/
66+
String description() default "";
67+
68+
/**
69+
* The operations available under this Path Item.
70+
* <p>
71+
* The {@link PathItemOperation#method() method} MUST be defined for each operation.
72+
*
73+
* @return the list of operations
74+
*/
75+
PathItemOperation[] operations() default {};
76+
77+
/**
78+
* A list of servers to be used for this Path Item, overriding those defined for the whole API.
79+
*
80+
* @return the list of servers
81+
*/
82+
Server[] servers() default {};
83+
84+
/**
85+
* A list of parameters which apply to all operations under this path item.
86+
*
87+
* @return the list of parameters
88+
*/
89+
Parameter[] parameters() default {};
90+
91+
/**
92+
* List of extensions to be added to the {@link org.eclipse.microprofile.openapi.models.PathItem PathItem} model
93+
* corresponding to the containing annotation.
94+
*
95+
* @return the list of extensions
96+
*/
97+
Extension[] extensions() default {};
98+
}

‎api/src/main/java/org/eclipse/microprofile/openapi/annotations/PathItemOperation.java

Lines changed: 175 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,175 @@
1+
/*
2+
* Copyright (c) 2024 Contributors to the Eclipse Foundation
3+
* <p>
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
* <p>
8+
* http://www.apache.org/licenses/LICENSE-2.0
9+
* <p>
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
package org.eclipse.microprofile.openapi.annotations;
17+
18+
import java.lang.annotation.Retention;
19+
import java.lang.annotation.RetentionPolicy;
20+
import java.lang.annotation.Target;
21+
22+
import org.eclipse.microprofile.openapi.annotations.callbacks.Callback;
23+
import org.eclipse.microprofile.openapi.annotations.extensions.Extension;
24+
import org.eclipse.microprofile.openapi.annotations.parameters.Parameter;
25+
import org.eclipse.microprofile.openapi.annotations.parameters.RequestBody;
26+
import org.eclipse.microprofile.openapi.annotations.responses.APIResponse;
27+
import org.eclipse.microprofile.openapi.annotations.security.SecurityRequirement;
28+
import org.eclipse.microprofile.openapi.annotations.security.SecurityRequirementsSet;
29+
import org.eclipse.microprofile.openapi.annotations.servers.Server;
30+
31+
/**
32+
* Describes an Operation
33+
* <p>
34+
* This annotation is only used for operations defined under a {@link PathItem}. For operations provided by the API
35+
* itself, it's more common to use the {@link Operation} annotation applied to a Jakarta REST resource method instead.
36+
*
37+
* @since 4.0
38+
*/
39+
@Target({})
40+
@Retention(RetentionPolicy.RUNTIME)
41+
public @interface PathItemOperation {
42+
43+
/**
44+
* The HTTP method for this operation.
45+
*
46+
* @return the HTTP method of this operation
47+
**/
48+
String method();
49+
50+
/**
51+
* The tag names which apply to this operation.
52+
*
53+
* @return the list of tag names
54+
*/
55+
String[] tags() default {}; // Could be @Tag[]
56+
57+
/**
58+
* Provides a brief description of what this operation does.
59+
*
60+
* @return a summary of this operation
61+
**/
62+
String summary() default "";
63+
64+
/**
65+
* A verbose description of the operation behavior. CommonMark syntax MAY be used for rich text representation.
66+
*
67+
* @return a description of this operation
68+
**/
69+
String description() default "";
70+
71+
/**
72+
* Additional external documentation for this operation.
73+
*
74+
* @return external documentation associated with this operation instance
75+
**/
76+
ExternalDocumentation externalDocs() default @ExternalDocumentation();
77+
78+
/**
79+
* Unique string used to identify the operation. The id MUST be unique among all operations described in the API.
80+
* <p>
81+
* Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is RECOMMENDED to
82+
* follow common programming naming conventions.
83+
* </p>
84+
*
85+
* @return the ID of this operation
86+
**/
87+
String operationId() default "";
88+
89+
/**
90+
* An array of parameters applicable for this operation.
91+
* <p>
92+
* The list MUST NOT include duplicated parameters. A unique parameter is defined by a combination of a name and
93+
* location.
94+
* </p>
95+
*
96+
* @return the list of parameters for this operation
97+
**/
98+
Parameter[] parameters() default {};
99+
100+
/**
101+
* The request body for this operation.
102+
*
103+
* @return the request body of this operation
104+
**/
105+
RequestBody requestBody() default @RequestBody();
106+
107+
/**
108+
* The list of possible responses that can be returned when executing this operation.
109+
*
110+
* @return the list of responses for this operation
111+
**/
112+
APIResponse[] responses() default {};
113+
114+
/**
115+
* A list of possible out-of-band callbacks related to this operation. Each entry represents a set of requests that
116+
* may be initiated by the API provided and an expression, evaluated at runtime, that identifies the URL used to
117+
* make those requests.
118+
*
119+
* @return the list of callbacks for this operation
120+
*/
121+
Callback[] callbacks() default {};
122+
123+
/**
124+
* Allows an operation to be marked as deprecated
125+
* <p>
126+
* Consumers SHOULD refrain from usage of a deprecated operation.
127+
* </p>
128+
*
129+
* @return whether or not this operation is deprecated
130+
**/
131+
boolean deprecated() default false;
132+
133+
/**
134+
* A declaration of which security mechanisms can be used for this callback operation. Only one of the security
135+
* requirement objects need to be satisfied to authorize a request.
136+
* <p>
137+
* Adding a {@code SecurityRequirement} to this array is equivalent to adding a {@code SecurityRequirementsSet}
138+
* containing a single {@code SecurityRequirement} to {@link #securitySets()}.
139+
* <p>
140+
* This definition overrides any declared top-level security. To remove a top-level security declaration, an empty
141+
* array can be used.
142+
*
143+
* @return the list of security mechanisms for this operation
144+
*/
145+
SecurityRequirement[] security() default {};
146+
147+
/**
148+
* A declaration of which security mechanisms can be used for this callback operation. All of the security
149+
* requirements within any one of the sets needs needs to be satisfied to authorize a request.
150+
* <p>
151+
* This definition overrides any declared top-level security. To remove a top-level security declaration, an empty
152+
* array can be used.
153+
* <p>
154+
* Including an empty set within this list indicates that the other requirements are optional.
155+
*
156+
* @return the list of security mechanisms for this operation
157+
*/
158+
SecurityRequirementsSet[] securitySets() default {};
159+
160+
/**
161+
* A list of servers to be used for this operation, overriding those defined for the parent path item or for the
162+
* whole API.
163+
*
164+
* @return the list of servers
165+
*/
166+
Server[] servers() default {};
167+
168+
/**
169+
* List of extensions to be added to the {@link org.eclipse.microprofile.openapi.models.Operation Operation} model
170+
* corresponding to the containing annotation.
171+
*
172+
* @return array of extensions
173+
*/
174+
Extension[] extensions() default {};
175+
}

‎api/src/main/java/org/eclipse/microprofile/openapi/annotations/callbacks/Callback.java

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -77,6 +77,16 @@
7777
**/
7878
String ref() default "";
7979

80+
/**
81+
* Reference value to a Path Item object, to be referenced by the Callback object.
82+
* <p>
83+
* This property provides a reference to a Path Item object defined elsewhere. {@code #callbackUrlExpression()} is
84+
* REQUIRED when this property is set. The referenced Path Item will be used for the URL expression specified.
85+
*
86+
* @since 4.0
87+
*/
88+
String pathItemRef() default "";
89+
8090
/**
8191
* List of extensions to be added to the {@link org.eclipse.microprofile.openapi.models.callbacks.Callback Callback}
8292
* model corresponding to the containing annotation.

‎api/src/main/java/org/eclipse/microprofile/openapi/annotations/callbacks/package-info.java

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,6 @@
4444
* </pre>
4545
*/
4646

47-
@org.osgi.annotation.versioning.Version("1.1")
47+
@org.osgi.annotation.versioning.Version("1.2")
4848
@org.osgi.annotation.versioning.ProviderType
4949
package org.eclipse.microprofile.openapi.annotations.callbacks;

‎api/src/main/java/org/eclipse/microprofile/openapi/annotations/package-info.java

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,5 +34,5 @@
3434
* </pre>
3535
*/
3636

37-
@org.osgi.annotation.versioning.Version("1.1")
37+
@org.osgi.annotation.versioning.Version("1.2")
3838
package org.eclipse.microprofile.openapi.annotations;

0 commit comments

Comments
 (0)