Merge pull request #629 from Azquelt/path-item-annotations

PathItem and PathItemOperation annotations

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

@@ -107,6 +107,15 @@
      */
     Callback[] callbacks() default {};
 
+    /**
+     * An object to hold reusable Path Item Objects.
+     *
+     * @return the reusable PathItem objects.
+     *
+     * @since 4.0
+     */
+    PathItem[] pathItems() default {};
+
     /**
      * List of extensions to be added to the {@link org.eclipse.microprofile.openapi.models.Components Components} model
      * corresponding to the containing annotation.

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

@@ -93,6 +93,15 @@
      */
     ExternalDocumentation externalDocs() default @ExternalDocumentation;
 
+    /**
+     * An array of webhook definitions which the API may be instructed to call using out-of-band mechanisms.
+     *
+     * @return the array of webhooks
+     *
+     * @since 4.0
+     */
+    PathItem[] webhooks() default {};
+
     /**
      * An element to hold a set of reusable objects for different aspects of the OpenAPI Specification (OAS).
      *

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

@@ -0,0 +1,99 @@
+/*
+ * Copyright (c) 2024 Contributors to the Eclipse Foundation
+ * <p>
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * <p>
+ * http://www.apache.org/licenses/LICENSE-2.0
+ * <p>
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.eclipse.microprofile.openapi.annotations;
+
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import org.eclipse.microprofile.openapi.annotations.extensions.Extension;
+import org.eclipse.microprofile.openapi.annotations.parameters.Parameter;
+import org.eclipse.microprofile.openapi.annotations.servers.Server;
+
+/**
+ * Describes a set of operations available on a single path.
+ *
+ * @since 4.0
+ */
+@Target({})
+@Retention(RetentionPolicy.RUNTIME)
+public @interface PathItem {
+
+    /**
+     * The name of the Path Item object, used as the map key when the path item is used under
+     * {@link Components#pathItems()} or {@link OpenAPIDefinition#webhooks()}
+     *
+     * @return the path item name
+     */
+    String name();
+
+    /**
+     * Reference value to a PathItem object.
+     * <p>
+     * This property provides a reference to an object defined elsewhere.
+     * <p>
+     * Unlike {@code ref} on most MP OpenAPI annotations, this property is <em>not</em> mutually exclusive with other
+     * properties.
+     *
+     * @return reference to a path item object definition
+     **/
+    String ref() default "";
+
+    /**
+     * The summary of the path item.
+     *
+     * @return the summary
+     */
+    String summary() default "";
+
+    /**
+     * The description of the path item.
+     *
+     * @return the description
+     */
+    String description() default "";
+
+    /**
+     * The operations available under this Path Item.
+     * <p>
+     * The {@link PathItemOperation#method() method} MUST be defined for each operation.
+     *
+     * @return the list of operations
+     */
+    PathItemOperation[] operations() default {};
+
+    /**
+     * A list of servers to be used for this Path Item, overriding those defined for the whole API.
+     *
+     * @return the list of servers
+     */
+    Server[] servers() default {};
+
+    /**
+     * A list of parameters which apply to all operations under this path item.
+     *
+     * @return the list of parameters
+     */
+    Parameter[] parameters() default {};
+
+    /**
+     * List of extensions to be added to the {@link org.eclipse.microprofile.openapi.models.PathItem PathItem} model
+     * corresponding to the containing annotation.
+     *
+     * @return the list of extensions
+     */
+    Extension[] extensions() default {};
+}

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

@@ -0,0 +1,176 @@
+/*
+ * Copyright (c) 2024 Contributors to the Eclipse Foundation
+ * <p>
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * <p>
+ * http://www.apache.org/licenses/LICENSE-2.0
+ * <p>
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.eclipse.microprofile.openapi.annotations;
+
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import org.eclipse.microprofile.openapi.annotations.callbacks.Callback;
+import org.eclipse.microprofile.openapi.annotations.extensions.Extension;
+import org.eclipse.microprofile.openapi.annotations.parameters.Parameter;
+import org.eclipse.microprofile.openapi.annotations.parameters.RequestBody;
+import org.eclipse.microprofile.openapi.annotations.responses.APIResponse;
+import org.eclipse.microprofile.openapi.annotations.security.SecurityRequirement;
+import org.eclipse.microprofile.openapi.annotations.security.SecurityRequirementsSet;
+import org.eclipse.microprofile.openapi.annotations.servers.Server;
+import org.eclipse.microprofile.openapi.annotations.tags.Tag;
+
+/**
+ * Describes an Operation
+ * <p>
+ * This annotation is only used for operations defined under a {@link PathItem}. For operations provided by the API
+ * itself, it's more common to use the {@link Operation} annotation applied to a Jakarta REST resource method instead.
+ *
+ * @since 4.0
+ */
+@Target({})
+@Retention(RetentionPolicy.RUNTIME)
+public @interface PathItemOperation {
+
+    /**
+     * The HTTP method for this operation.
+     *
+     * @return the HTTP method of this operation
+     **/
+    String method();
+
+    /**
+     * The tags which apply to this operation.
+     *
+     * @return the list of tags
+     */
+    Tag[] tags() default {};
+
+    /**
+     * Provides a brief description of what this operation does.
+     *
+     * @return a summary of this operation
+     **/
+    String summary() default "";
+
+    /**
+     * A verbose description of the operation behavior. CommonMark syntax MAY be used for rich text representation.
+     *
+     * @return a description of this operation
+     **/
+    String description() default "";
+
+    /**
+     * Additional external documentation for this operation.
+     *
+     * @return external documentation associated with this operation instance
+     **/
+    ExternalDocumentation externalDocs() default @ExternalDocumentation();
+
+    /**
+     * Unique string used to identify the operation. The id MUST be unique among all operations described in the API.
+     * <p>
+     * Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is RECOMMENDED to
+     * follow common programming naming conventions.
+     * </p>
+     *
+     * @return the ID of this operation
+     **/
+    String operationId() default "";
+
+    /**
+     * An array of parameters applicable for this operation.
+     * <p>
+     * The list MUST NOT include duplicated parameters. A unique parameter is defined by a combination of a name and
+     * location.
+     * </p>
+     *
+     * @return the list of parameters for this operation
+     **/
+    Parameter[] parameters() default {};
+
+    /**
+     * The request body for this operation.
+     *
+     * @return the request body of this operation
+     **/
+    RequestBody requestBody() default @RequestBody();
+
+    /**
+     * The list of possible responses that can be returned when executing this operation.
+     *
+     * @return the list of responses for this operation
+     **/
+    APIResponse[] responses() default {};
+
+    /**
+     * A list of possible out-of-band callbacks related to this operation. Each entry represents a set of requests that
+     * may be initiated by the API provided and an expression, evaluated at runtime, that identifies the URL used to
+     * make those requests.
+     *
+     * @return the list of callbacks for this operation
+     */
+    Callback[] callbacks() default {};
+
+    /**
+     * Allows an operation to be marked as deprecated
+     * <p>
+     * Consumers SHOULD refrain from usage of a deprecated operation.
+     * </p>
+     *
+     * @return whether or not this operation is deprecated
+     **/
+    boolean deprecated() default false;
+
+    /**
+     * A declaration of which security mechanisms can be used for this callback operation. Only one of the security
+     * requirement objects need to be satisfied to authorize a request.
+     * <p>
+     * Adding a {@code SecurityRequirement} to this array is equivalent to adding a {@code SecurityRequirementsSet}
+     * containing a single {@code SecurityRequirement} to {@link #securitySets()}.
+     * <p>
+     * This definition overrides any declared top-level security. To remove a top-level security declaration, an empty
+     * array can be used.
+     *
+     * @return the list of security mechanisms for this operation
+     */
+    SecurityRequirement[] security() default {};
+
+    /**
+     * A declaration of which security mechanisms can be used for this callback operation. All of the security
+     * requirements within any one of the sets needs needs to be satisfied to authorize a request.
+     * <p>
+     * This definition overrides any declared top-level security. To remove a top-level security declaration, an empty
+     * array can be used.
+     * <p>
+     * Including an empty set within this list indicates that the other requirements are optional.
+     *
+     * @return the list of security mechanisms for this operation
+     */
+    SecurityRequirementsSet[] securitySets() default {};
+
+    /**
+     * A list of servers to be used for this operation, overriding those defined for the parent path item or for the
+     * whole API.
+     *
+     * @return the list of servers
+     */
+    Server[] servers() default {};
+
+    /**
+     * List of extensions to be added to the {@link org.eclipse.microprofile.openapi.models.Operation Operation} model
+     * corresponding to the containing annotation.
+     *
+     * @return array of extensions
+     */
+    Extension[] extensions() default {};
+}

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

@@ -77,6 +77,16 @@
      **/
     String ref() default "";
 
+    /**
+     * Reference value to a Path Item object, to be referenced by the Callback object.
+     * <p>
+     * This property provides a reference to a Path Item object defined elsewhere. {@code #callbackUrlExpression()} is
+     * REQUIRED when this property is set. The referenced Path Item will be used for the URL expression specified.
+     *
+     * @since 4.0
+     */
+    String pathItemRef() default "";
+
     /**
      * List of extensions to be added to the {@link org.eclipse.microprofile.openapi.models.callbacks.Callback Callback}
      * model corresponding to the containing annotation.

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

@@ -44,6 +44,6 @@
  * </pre>
  */
 
-@org.osgi.annotation.versioning.Version("1.1")
+@org.osgi.annotation.versioning.Version("1.2")
 @org.osgi.annotation.versioning.ProviderType
 package org.eclipse.microprofile.openapi.annotations.callbacks;

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

@@ -34,5 +34,5 @@
  * </pre>
  */
 
-@org.osgi.annotation.versioning.Version("1.1")
+@org.osgi.annotation.versioning.Version("1.2")
 package org.eclipse.microprofile.openapi.annotations;