PathItem.ref is allowed with other properties

microprofile · Jun 7, 2024 · fc47197 · fc47197
1 parent 81281df
commit fc47197
Show file tree

Hide file tree

Showing 3 changed files with 23 additions and 5 deletions.
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/PathItem.java b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/PathItem.java
@@ -43,11 +43,12 @@
     /**
      * Reference value to a PathItem object.
      * <p>
-     * This property provides a reference to an object defined elsewhere. This property and properties other than
-     * {@link #name()} are mutually exclusive. If properties other than {@code name} are defined in addition to the
-     * {@code ref} property then the result is undefined.
+     * 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 callback object definition
+     * @return reference to a path item object definition
      **/
     String ref() default "";
 

diff --git a/tck/src/main/java/org/eclipse/microprofile/openapi/apps/airlines/JAXRSApp.java b/tck/src/main/java/org/eclipse/microprofile/openapi/apps/airlines/JAXRSApp.java
@@ -289,7 +289,19 @@
                                                     @PathItem(name = "UserEventARef",
                                                               ref = "#/components/pathItems/UserEvent",
                                                               description = "UserEvent reference",
-                                                              summary = "Referenced PathItem"),
+                                                              summary = "Referenced PathItem",
+                                                              operations = @PathItemOperation(
+                                                                                              method = "POST",
+                                                                                              summary = "User updated event",
+                                                                                              description = "A user was modified",
+                                                                                              requestBody = @RequestBody(
+                                                                                                                         description = "The modified user",
+                                                                                                                         content = @Content(mediaType = MediaType.APPLICATION_JSON,
+                                                                                                                                            schema = @Schema(ref = "User"))),
+                                                                                              responses = {
+                                                                                                      @APIResponse(responseCode = "200",
+                                                                                                                   description = "Event received")
+                                                                                              })),
                                                     @PathItem(name = "CallbackPathItem",
                                                               operations = @PathItemOperation(
                                                                                               method = "POST",

diff --git a/tck/src/main/java/org/eclipse/microprofile/openapi/tck/AirlinesAppTest.java b/tck/src/main/java/org/eclipse/microprofile/openapi/tck/AirlinesAppTest.java
@@ -1212,6 +1212,11 @@ public void testPathItem(String type) {
         vr.body(pathItem + ".servers[0].url", equalTo("http://example.com"));
         vr.body(pathItem + ".parameters[0].name", equalTo("id"));
         vr.body(pathItem + ".x-pathItem", equalTo("test path item"));
+
+        pathItem = "components.pathItems.UserEventARef";
+        vr.body(pathItem + ".$ref", equalTo("#/components/pathItems/UserEvent"));
+        vr.body(pathItem + ".post", notNullValue());
+        vr.body(pathItem + ".post.summary", equalTo("User updated event"));
     }
 
     @Test(dataProvider = "formatProvider")