Merge pull request #627 from Azquelt/requestbody-default-required

Make request body required by default

Author: Azquelt

api/src/main/java/org/eclipse/microprofile/openapi/annotations/parameters/RequestBody.java

@@ -56,10 +56,14 @@
 
     /**
      * Determines if the request body is required in the request.
+     * <p>
+     * Note that the default value of this property is {@code true}, while the default value of the {@code required}
+     * property in the OpenAPI specification is {@code false}, because Jakarta REST resource methods which accept a
+     * request body generally require it.
      *
      * @return whether or not this requestBody is required
      **/
-    boolean required() default false;
+    boolean required() default true;
 
     /**
      * The unique name to identify this request body. Unless this annotation is used on the actual request body

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

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

tck/src/main/java/org/eclipse/microprofile/openapi/apps/airlines/JAXRSApp.java

@@ -172,8 +172,17 @@
                                                     @RequestBody(name = "review",
                                                                  content = @Content(mediaType = MediaType.APPLICATION_JSON,
                                                                                     schema = @Schema(implementation = Review.class)),
-                                                                 required = true,
                                                                  description = "example review to add"),
+                                                    @RequestBody(name = "nonRequiredReview",
+                                                                 content = @Content(mediaType = MediaType.APPLICATION_JSON,
+                                                                                    schema = @Schema(implementation = Review.class)),
+                                                                 required = false,
+                                                                 description = "example non-required review"),
+                                                    @RequestBody(name = "requiredReview",
+                                                                 content = @Content(mediaType = MediaType.APPLICATION_JSON,
+                                                                                    schema = @Schema(implementation = Review.class)),
+                                                                 required = true,
+                                                                 description = "example required review"),
                                                     @RequestBody(name = "reviewARef",
                                                                  ref = "#/components/requestBodies/review",
                                                                  description = "Review reference")

tck/src/main/java/org/eclipse/microprofile/openapi/apps/airlines/resources/UserResource.java

@@ -148,7 +148,7 @@ public Response createUser(
     /* tags = {"user"}, //this operation intentionally doesn't have tags attribute, since above Tag ref should apply */
     )
     public Response createUsersWithArrayInput(
-            @RequestBody(description = "Array of user object", required = true,
+            @RequestBody(description = "Array of user object",
                          content = @Content(mediaType = "application/json",
                                             schema = @Schema(type = SchemaType.ARRAY, implementation = User.class,
                                                              nullable = true, writeOnly = true, minItems = 2,
@@ -168,7 +168,7 @@ public Response createUsersWithArrayInput(
     @Operation(summary = "Creates list of users with given input list", // List of User objects
                operationId = "createUsersFromList")
     public Response createUsersWithListInput(
-            @RequestBody(description = "List of user object", required = true) java.util.List<User> users) {
+            @RequestBody(description = "List of user object") java.util.List<User> users) {
         for (User user : users) {
             userData.addUser(user);
         }
@@ -177,7 +177,7 @@ public Response createUsersWithListInput(
 
     @Path("/username/{username}")
     @PUT
-    @RequestBody(name = "user", description = "Record of a new user to be created in the system.",
+    @RequestBody(name = "user", description = "Record of a new user to be created in the system.", required = false,
                  content = @Content(mediaType = "application/json", schema = @Schema(implementation = User.class),
                                     examples = @ExampleObject(name = "user",
                                                               summary = "Example user properties to update",

tck/src/main/java/org/eclipse/microprofile/openapi/apps/petstore/resource/PetResource.java

@@ -172,7 +172,7 @@ public Response deletePet(
     @RequestBody(name = "pet",
                  content = @Content(mediaType = "application/json", schema = @Schema(implementation = Pet.class),
                                     examples = @ExampleObject(ref = "http://example.org/petapi-examples/openapi.json#/components/examples/pet-example")),
-                 required = true, description = "example of a new pet to add")
+                 description = "example of a new pet to add")
     @Operation(summary = "Add pet to store", description = "Add a new pet to the store")
     public Response addPet(Pet pet) {
         Pet updatedPet = petData.addPet(pet);
@@ -193,7 +193,6 @@ public Response addPet(Pet pet) {
     @Operation(summary = "Update an existing pet", description = "Update an existing pet with the given new attributes")
     public Response updatePet(
             @RequestBody(description = "Attribute to update existing pet record",
-                         required = true,
                          content = @Content(schema = @Schema(implementation = Pet.class))) Pet pet) {
         Pet updatedPet = petData.addPet(pet);
         return Response.ok().entity(updatedPet).build();

tck/src/main/java/org/eclipse/microprofile/openapi/apps/petstore/resource/PetStoreResource.java

@@ -115,7 +115,7 @@ public Response getOrderById(
     @APIResponse(responseCode = "200", description = "successful operation")
     @APIResponse(responseCode = "400", description = "Invalid Order")
     public Order placeOrder(
-            @RequestBody(description = "order placed for purchasing the pet", required = true) Order order) {
+            @RequestBody(description = "order placed for purchasing the pet") Order order) {
         storeData.placeOrder(order);
         return storeData.placeOrder(order);
     }

tck/src/main/java/org/eclipse/microprofile/openapi/apps/petstore/resource/UserResource.java

@@ -69,8 +69,7 @@ public class UserResource {
     })
     public Response createUser(
             @RequestBody(description = "Created user object",
-                         content = @Content(schema = @Schema(ref = "#/components/schemas/User")),
-                         required = true) User user) {
+                         content = @Content(schema = @Schema(ref = "#/components/schemas/User"))) User user) {
         userData.addUser(user);
         return Response.ok().entity("").build();
     }
@@ -112,7 +111,7 @@ public Response updateUser(
             @Parameter(name = "username", description = "name that need to be deleted",
                        schema = @Schema(type = SchemaType.STRING),
                        required = true) @PathParam("username") String username,
-            @RequestBody(description = "Updated user object", required = true) User user) {
+            @RequestBody(description = "Updated user object") User user) {
         userData.addUser(user);
         return Response.ok().entity("").build();
     }

tck/src/main/java/org/eclipse/microprofile/openapi/tck/AirlinesAppTest.java

@@ -502,9 +502,16 @@ public void testRequestBodyAnnotations(String type) {
         vr.body(endpoint + ".description", equalTo("Create a new booking with the provided information."));
         vr.body(endpoint + ".content", notNullValue());
         vr.body(endpoint + ".x-request-body", equalTo("test-request-body"));
+        vr.body(endpoint + ".required", equalTo(true));
 
+        // PUT method with entity parameter but no @RequestBody annotation
         endpoint = "paths.'/bookings/{id}'.put.requestBody";
         vr.body(endpoint + ".content", notNullValue());
+        vr.body(endpoint + ".required", equalTo(true));
+
+        // GET method without @RequestBody annotation
+        endpoint = "paths.'/bookings/{id}'.get.requestBody";
+        vr.body(endpoint, nullValue());
 
         endpoint = "paths.'/user'.post.requestBody";
         vr.body(endpoint + ".description", equalTo("Record of a new user to be created in the system."));
@@ -514,6 +521,7 @@ public void testRequestBodyAnnotations(String type) {
         endpoint = "paths.'/user/username/{username}'.put.requestBody";
         vr.body(endpoint + ".description", equalTo("Record of a new user to be created in the system."));
         vr.body(endpoint + ".content", notNullValue());
+        vr.body(endpoint + ".required", either(nullValue()).or(equalTo(false)));
 
         endpoint = "paths.'/user/createWithArray'.post.requestBody";
         vr.body(endpoint + ".description", equalTo("Array of user object"));
@@ -524,6 +532,21 @@ public void testRequestBodyAnnotations(String type) {
         vr.body(endpoint + ".description", equalTo("List of user object"));
         vr.body(endpoint + ".content", notNullValue());
         vr.body(endpoint + ".required", equalTo(true));
+
+        endpoint = "components.requestBodies.review";
+        vr.body(endpoint + ".description", equalTo("example review to add"));
+        vr.body(endpoint + ".content", notNullValue());
+        vr.body(endpoint + ".required", equalTo(true));
+
+        endpoint = "components.requestBodies.nonRequiredReview";
+        vr.body(endpoint + ".description", equalTo("example non-required review"));
+        vr.body(endpoint + ".content", notNullValue());
+        vr.body(endpoint + ".required", either(nullValue()).or(equalTo(false)));
+
+        endpoint = "components.requestBodies.requiredReview";
+        vr.body(endpoint + ".description", equalTo("example required review"));
+        vr.body(endpoint + ".content", notNullValue());
+        vr.body(endpoint + ".required", equalTo(true));
     }
 
     @Test(dataProvider = "formatProvider")