Repository: eclipse/microprofile-open-api
Pull request #133 (2017-12-07 20:44:18)

Update petstore and airlines apps to use modified Operation and new Ca…
…llbackOperation  annotation

Signed-off-by: leochr <leojc@ca.ibm.com>


Patch:
diff --git a/spec/src/main/asciidoc/microprofile-openapi-spec.adoc b/spec/src/main/asciidoc/microprofile-openapi-spec.adoc
index 48bff82..6c204cb 100644
--- a/spec/src/main/asciidoc/microprofile-openapi-spec.adoc
+++ b/spec/src/main/asciidoc/microprofile-openapi-spec.adoc
@@ -161,7 +161,6 @@ The following annotations are found in the https://github.com/eclipse/microprofi
 
 | https://github.com/eclipse/microprofile-open-api/blob/master/api/src/main/java/org/eclipse/microprofile/openapi/annotations/callbacks/Callback.java[@Callback] | Represents a callback URL that will be invoked.
 | https://github.com/eclipse/microprofile-open-api/blob/master/api/src/main/java/org/eclipse/microprofile/openapi/annotations/callbacks/Callbacks.java[@Callbacks] | Represents an array of Callback URLs that can be invoked.
-| https://github.com/eclipse/microprofile-open-api/blob/master/api/src/main/java/org/eclipse/microprofile/openapi/annotations/callbacks/CallbackOperation.java[@CallbackOperation] | Represents an operation that will be invoked during the callback.
 | https://github.com/eclipse/microprofile-open-api/blob/master/api/src/main/java/org/eclipse/microprofile/openapi/annotations/Components.java[@Components] | A container that holds various reusable objects for different aspects of the OpenAPI Specification.
 | https://github.com/eclipse/microprofile-open-api/blob/master/api/src/main/java/org/eclipse/microprofile/openapi/annotations/enums/Explode.java[@Explode] | Enumeration used to define the value of the `explode` property.
 | https://github.com/eclipse/microprofile-open-api/blob/master/api/src/main/java/org/eclipse/microprofile/openapi/annotations/enums/ParameterIn.java[@ParameterIn] | Enumeration representing the parameter's `in` property.
@@ -233,11 +232,12 @@ public Response findPetsByStatus(...) { ... }
 ----
 @GET
 @Path("/{username}")
-@Operation(summary = "Get user by user name")
-@APIResponse(description = "The user",
-             content = @Content(mediaType = "application/json",
-                                schema = @Schema(implementation = User.class))),
-@APIResponse(responseCode = "400", description = "User not found")
+@Operation(summary = "Get user by user name",
+           responses = {
+                @APIResponse(description = "The user",
+                             content = @Content(mediaType = "application/json",
+                             schema = @Schema(implementation = User.class))),
+                @APIResponse(responseCode = "400", description = "User not found")})
 public Response getUserByName(
         @Parameter(description = "The name that needs to be fetched. Use user1 for testing. ", required = true) @PathParam("username") String username)
  {...}
@@ -279,9 +279,10 @@ public Response getUserByName(
 @Path("/user")
 @Operation(summary = "Create user",
            description = "This can only be done by the logged in user.")
-public Response methodWithRequestBody(
+public Response methodWithRequestBodyAndTwoParameters(
           @RequestBody(description = "Created user object", required = true,
-                       content = @Content(schema = @Schema(implementation = User.class))) User user,
+                       content = @Content(
+                       schema = @Schema(implementation = User.class))) User user,
           @QueryParam("name") String name, @QueryParam("code") String code)
           { ... }
 ----
@@ -292,7 +293,7 @@ public Response methodWithRequestBody(
 post:
     summary: Create user
       description: This can only be done by the logged in user.
-      operationId: methodWithRequestBody
+      operationId: methodWithRequestBodyAndTwoParameters
     parameters:
     - name: name
       in: query
@@ -323,56 +324,49 @@ post:
     servers = {
         @Server(
             description = "definition server 1",
-            url = "http://{var1}.definition1/{var2}",
+            url = "http://definition1",
             variables = {
-                @ServerVariable(name = "var1",
-                                description = "var 1",
-                                defaultValue = "1",
-                                enumeration = {"1", "2"}),
-                @ServerVariable(name = "var2",
-                                description = "var 2",
-                                defaultValue = "1",
-                                enumeration = {"1", "2"})})})
+                @ServerVariable(name = "var1", description = "var 1", defaultValue = "1", allowableValues = {"1", "2"}),
+                @ServerVariable(name = "var2", description = "var 2", defaultValue = "1", allowableValues = {"1", "2"})
+            })
+    }
+)
 @Server(
-    description = "class server 1",
-    url = "http://{var1}.class1/{var2}",
-    variables = {
-            @ServerVariable(
-                      name = "var1",
-                      description = "var 1",
-                      defaultValue = "1",
-                      enumeration = {"1", "2"}),
-            @ServerVariable(
-                      name = "var2",
-                      description = "var 2",
-                      defaultValue = "1",
-                      enumeration = {"1", "2"})})
+        description = "class server 1",
+        url = "http://class1",
+        variables = {
+                @ServerVariable(name = "var1", description = "var 1", defaultValue = "1", allowableValues = {"1", "2"}),
+                @ServerVariable(name = "var2", description = "var 2", defaultValue = "1", allowableValues = {"1", "2"})
+        })
 @Server(
-    description = "class server 2",
-    url = "http://{var1}.class2",
-    variables = {
-            @ServerVariable(
-                       name = "var1",
-                       description = "var 1",
-                       defaultValue = "1",
-                       enumeration = {"1", "2"})})
+        description = "class server 2",
+        url = "http://class2",
+        variables = {
+                @ServerVariable(name = "var1", description = "var 1", defaultValue = "1", allowableValues = {"1", "2"})
+        })
 public class ServersResource {
 
     @GET
     @Path("/")
+    @Operation(servers = {
+            @Server(
+                    description = "operation server 1",
+                    url = "http://op1",
+                    variables = {
+                            @ServerVariable(name = "var1", description = "var 1", defaultValue = "1", allowableValues = {"1", "2"})
+                    })
+    })
     @Server(
-        description = "method server 1",
-        url = "http://{var1}.method1",
-        variables = {
-            @ServerVariable(
-                      name = "var1",
-                      description = "var 1",
-                      defaultValue = "1",
-                      enumeration = {"1", "2"})})
+            description = "method server 1",
+            url = "http://method1",
+            variables = {
+                    @ServerVariable(name = "var1", description = "var 1", defaultValue = "1", allowableValues = {"1", "2"})
+            })
     @Server(
-        description = "method server 2",
-        url = "http://method2"
+            description = "method server 2",
+            url = "http://method2"
     )
+
     public Response getServers() {
         return Response.ok().entity("ok").build();
     }
@@ -384,7 +378,7 @@ public class ServersResource {
 ----
 openapi: 3.0.0
 servers:
-- url: http://{var1}.definition1/{var2}
+- url: http://definition1
   description: definition server 1
   variables:
     var1:
@@ -407,7 +401,7 @@ paths:
         default:
           description: default response
       servers:
-      - url: http://{var1}.class1/{var2}
+      - url: http://class1
         description: class server 1
         variables:
           var1:
@@ -422,7 +416,7 @@ paths:
             - "1"
             - "2"
             default: "1"
-      - url: http://{var1}.class2
+      - url: http://class2
         description: class server 2
         variables:
           var1:
@@ -431,7 +425,7 @@ paths:
             - "1"
             - "2"
             default: "1"
-      - url: http://{var1}.method1
+      - url: http://method1
         description: method server 1
         variables:
           var1:
@@ -443,6 +437,15 @@ paths:
       - url: http://method2
         description: method server 2
         variables: {}
+      - url: http://op1
+        description: operation server 1
+        variables:
+          var1:
+            description: var 1
+            enum:
+            - "1"
+            - "2"
+            default: "1"
 ----
 
 ===== Schema
@@ -598,6 +601,8 @@ The order of filter methods called is undefined, with two exceptions:
 2.  The `filterOpenAPI` method must be the *last* method called on a filter (which
 is just a specialization of the first exception).
 
+TODO: Document solution from issue #56 once ready
+
 === Processing rules
 
 The processed document available from the <<OpenAPI Endpoint>> is built from a variety of sources,
@@ -610,6 +615,14 @@ are required to process these different sources in the following order:
 4. Process annotations
 5. Filter model via OASFilter
 
+==== Validation
+
+The MP OpenAPI 1.0 specification does not mandate vendors to validate the resulting
+OpenAPI v3 model (after processing the 5 steps previously mentioned), which means
+that the behavior of invalid models is vendor specific (i.e. vendors may choose to
+ignore, reject, or pass-through invalid inputs).
+
+
 **Example processing**:
 
 * A vendor starts by fetching all available <<Configuration>>.  If
@@ -637,10 +650,6 @@ For example, `GET http://myHost:myPort/openapi`.
 
 This document represents the result of the applied <<Processing rules>>.
 
-The protocol required is `http`.  Vendors are encouraged, but not required, to
-support the `https` protocol as well, to enable a secure connection to the OpenAPI
-endpoint.
-
 === Content format
 The default format of the `/openapi` endpoint is `YAML`.
 
@@ -688,15 +697,3 @@ the various <<Documentation Mechanisms>>, so that the implementing framework can
 perform a global replacement of the keys with the language-specific text that
 matches the `Accept-Language` request for the `/openapi` endpoint.  A cache of
 processed languages can be kept to improve performance.
-
-=== Validation
-
-The MP OpenAPI 1.0 specification does not mandate vendors to validate the resulting
-OpenAPI v3 model (after processing the 5 steps previously mentioned), which means
-that the behavior of invalid models is vendor specific (i.e. vendors may choose to
-ignore, reject, or pass-through invalid inputs).
-
-=== Cross Origin Resource Sharing (CORS)
-
-The MP OpenAPI 1.0 specification does not require vendors to support https://www.w3.org/TR/cors/[CORS]
-for the `/openapi` endpoint.  The behavior of CORS requests is implementation dependent.
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
index 3c929dd..7934804 100644
--- 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
@@ -42,8 +42,8 @@ import org.eclipse.microprofile.openapi.annotations.enums.SecuritySchemeType;
 import org.eclipse.microprofile.openapi.annotations.headers.Header;
 import org.eclipse.microprofile.openapi.annotations.ExternalDocumentation;
 import org.eclipse.microprofile.openapi.annotations.OpenAPIDefinition;
-import org.eclipse.microprofile.openapi.annotations.Operation;
 import org.eclipse.microprofile.openapi.annotations.callbacks.Callback;
+import org.eclipse.microprofile.openapi.annotations.callbacks.CallbackOperation;
 import org.eclipse.microprofile.openapi.annotations.Components;
 import org.eclipse.microprofile.openapi.apps.airlines.model.Airline;
 import org.eclipse.microprofile.openapi.apps.airlines.model.Booking;
@@ -120,7 +120,7 @@ import org.eclipse.microprofile.openapi.apps.airlines.resources.ReviewResource;
                                 parameters = @LinkParameter(name = "userId", expression = "$request.path.id")) }, 
                 callbacks = {
                         @Callback(name = "GetBookings", callbackUrlExpression = "http://localhost:9080/airlines/bookings", 
-                                operation = @Operation(summary = "Retrieve all bookings for current user", 
+                                operations = @CallbackOperation(summary = "Retrieve all bookings for current user", 
                                 responses = {@APIResponse(ref = "FoundBookings") })) 
                         }))
 @SecurityScheme(
diff --git a/tck/src/main/java/org/eclipse/microprofile/openapi/apps/airlines/resources/AirlinesResource.java b/tck/src/main/java/org/eclipse/microprofile/openapi/apps/airlines/resources/AirlinesResource.java
index 31b17c9..686648a 100644
--- a/tck/src/main/java/org/eclipse/microprofile/openapi/apps/airlines/resources/AirlinesResource.java
+++ b/tck/src/main/java/org/eclipse/microprofile/openapi/apps/airlines/resources/AirlinesResource.java
@@ -23,6 +23,7 @@ import javax.ws.rs.core.Response;
 
 import org.eclipse.microprofile.openapi.annotations.Operation;
 import org.eclipse.microprofile.openapi.annotations.callbacks.Callback;
+import org.eclipse.microprofile.openapi.annotations.callbacks.CallbackOperation;
 import org.eclipse.microprofile.openapi.annotations.media.Content;
 import org.eclipse.microprofile.openapi.annotations.media.Schema;
 import org.eclipse.microprofile.openapi.annotations.responses.APIResponse;
@@ -43,11 +44,9 @@ import org.eclipse.microprofile.openapi.apps.airlines.model.Flight;
 @Callback(
     name = "availabilityCallback",
     callbackUrlExpression="http://localhost:9080/oas3-airlines/availability",
-    operation = @Operation(
+    operations = @CallbackOperation(
         method = "get",
         summary = "Retrieve all available flights",
-        operationId = "getFlights",
-        tags = {"availability"},
         responses = {
             @APIResponse(
                 responseCode = "200",
@@ -91,23 +90,20 @@ public class AirlinesResource {
             name = "Retrieve Airlines",
             description = "method to retrieve all airlines"
             )
+    @Tag(ref="airlines")
+    @APIResponse(
+            ref = "FoundAirlines"
+        )
+    @APIResponse(
+            responseCode = "404",
+            description = "No airlines found",
+            content = @Content(
+                mediaType = "n/a"
+            )
+        )
     @Operation(
-        method = "get",
         summary = "Retrieve all available airlines",
-        operationId = "getAirlines",
-        tags = {"airlines"},
-        responses = {
-            @APIResponse(
-                ref = "FoundAirlines"
-            ),
-            @APIResponse(
-                responseCode = "404",
-                description = "No airlines found",
-                content = @Content(
-                    mediaType = "n/a"
-                )
-            )
-        })
+        operationId = "getAirlines")
     @Produces("application/json")
     public Response getAirlines(){
         return Response.ok().entity(airlines.values()).build();
diff --git a/tck/src/main/java/org/eclipse/microprofile/openapi/apps/airlines/resources/AvailabilityResource.java b/tck/src/main/java/org/eclipse/microprofile/openapi/apps/airlines/resources/AvailabilityResource.java
index 83c04cb..06ee7f9 100644
--- a/tck/src/main/java/org/eclipse/microprofile/openapi/apps/airlines/resources/AvailabilityResource.java
+++ b/tck/src/main/java/org/eclipse/microprofile/openapi/apps/airlines/resources/AvailabilityResource.java
@@ -47,29 +47,26 @@ public class AvailabilityResource {
                 description = "A list of all the flights offered by the app",
                 url = "http://airlinesratingapp.com/ourflights")
         )
-    @Operation(
-        method = "get",
-        summary = "Retrieve all available flights",
-        operationId = "getFlights",
-        responses = {
-            @APIResponse(
-                responseCode = "200",
-                description = "successful operation",
-                content = @Content(
-                    mediaType = "applictaion/json",
-                    schema = @Schema(
-                        type = SchemaType.ARRAY,
-                        implementation = Flight.class
-                    )
+    @APIResponse(
+            responseCode = "200",
+            description = "successful operation",
+            content = @Content(
+                mediaType = "applictaion/json",
+                schema = @Schema(
+                    type = SchemaType.ARRAY,
+                    implementation = Flight.class
                 )
-            ),
-            @APIResponse(
-                responseCode = "404",
-                description = "No available flights found",
-                content = @Content(
-                    mediaType = "n/a")
             )
-        })
+        )
+    @APIResponse(
+            responseCode = "404",
+            description = "No available flights found",
+            content = @Content(
+                mediaType = "n/a")
+        )
+    @Operation(
+        summary = "Retrieve all available flights",
+        operationId = "getFlights")
     @Produces("application/json")
     public Response getFlights(
         @Parameter(
diff --git a/tck/src/main/java/org/eclipse/microprofile/openapi/apps/airlines/resources/BookingResource.java b/tck/src/main/java/org/eclipse/microprofile/openapi/apps/airlines/resources/BookingResource.java
index 4e0d73f..1619289 100644
--- a/tck/src/main/java/org/eclipse/microprofile/openapi/apps/airlines/resources/BookingResource.java
+++ b/tck/src/main/java/org/eclipse/microprofile/openapi/apps/airlines/resources/BookingResource.java
@@ -21,9 +21,11 @@ import org.eclipse.microprofile.openapi.annotations.enums.ParameterStyle;
 import org.eclipse.microprofile.openapi.annotations.parameters.RequestBody;
 import org.eclipse.microprofile.openapi.annotations.media.Content;
 import org.eclipse.microprofile.openapi.annotations.callbacks.Callback;
+import org.eclipse.microprofile.openapi.annotations.callbacks.CallbackOperation;
 import org.eclipse.microprofile.openapi.annotations.media.ExampleObject;
 import org.eclipse.microprofile.openapi.annotations.media.Schema;
 import org.eclipse.microprofile.openapi.annotations.responses.APIResponse;
+import org.eclipse.microprofile.openapi.annotations.responses.APIResponses;
 import org.eclipse.microprofile.openapi.annotations.tags.Tag;
 import org.eclipse.microprofile.openapi.annotations.tags.Tags;
 import org.eclipse.microprofile.openapi.annotations.enums.SecuritySchemeType;
@@ -69,34 +71,37 @@ public class BookingResource {
     private volatile int currentId = 0;
 
     @GET
+    @Tag(ref="booking")
+    @APIResponses(value={
+            @APIResponse(
+                    responseCode="200",
+                    description="Bookings retrieved",
+                    content=@Content(
+                        schema=@Schema(
+                            type = SchemaType.ARRAY,
+                            implementation=Booking.class))
+                    ),
+                @APIResponse(
+                    responseCode="404",
+                    description="No bookings found for the user.")
+    })
     @Operation(
-        method = "get",
         summary="Retrieve all bookings for current user",
-        operationId = "getAllBookings",
-        tags = {"booking"},
-        responses={
-            @APIResponse(
-                responseCode="200",
-                description="Bookings retrieved",
-                content=@Content(
-                    schema=@Schema(
-                        type = SchemaType.ARRAY,
-                        implementation=Booking.class))
-                ),
-            @APIResponse(
-                responseCode="404",
-                description="No bookings found for the user.")
-        })
+        operationId = "getAllBookings")
     @Produces("application/json")
     public Response getBookings(){
         return Response.ok().entity(bookings.values()).build();
     }
 
     @POST
+    @SecurityRequirement(
+            name = "bookingSecurityScheme",
+            scopes = {"write:bookings", "read:bookings"}
+        )
     @Callback(
         name = "get all the bookings",
         callbackUrlExpression = "http://localhost:9080/airlines/bookings",
-        operation = @Operation(
+        operations = @CallbackOperation(
             summary="Retrieve all bookings for current user",
             responses={
                 @APIResponse(
@@ -111,16 +116,25 @@ public class BookingResource {
                     responseCode="404",
                     description="No bookings found for the user.")
             }))
+    @APIResponse(
+            responseCode="201",
+            description="Booking created",
+            content = @Content(
+                schema=@Schema(
+                    name= "id",
+                    description = "id of the new booking",
+                    type=SchemaType.STRING
+                )
+            )
+        )
     @Operation(
-        method = "post",
         summary="Create a booking",
         description = "Create a new booking record with the booking information provided.",
-        operationId = "createBooking",
-        security = @SecurityRequirement(
-            name = "bookingSecurityScheme",
-            scopes = {"write:bookings", "read:bookings"}
-        ),
-        requestBody = @RequestBody(
+        operationId = "createBooking"
+    )
+    @Consumes("application/json")
+    @Produces("application/json")
+    public Response createBooking(@RequestBody(
             description = "Create a new booking with the provided information.",
             content = @Content(
                 mediaType = "application/json",
@@ -130,25 +144,7 @@ public class BookingResource {
                     summary = "External booking example",
                     externalValue = "http://foo.bar/examples/booking-example.json"
                 )
-            )
-        ),
-        responses={
-            @APIResponse(
-                responseCode="201",
-                description="Booking created",
-                content = @Content(
-                    schema=@Schema(
-                        name= "id",
-                        description = "id of the new booking",
-                        type=SchemaType.STRING
-                    )
-                )
-            )
-        }
-    )
-    @Consumes("application/json")
-    @Produces("application/json")
-    public Response createBooking(Booking task) {
+            )) Booking task) {
             bookings.put(currentId, task);
             return Response.status(Status.CREATED).entity("{\"id\":" + currentId++ + "}").build();
         }
@@ -166,22 +162,22 @@ public class BookingResource {
                     )
             }
             )
+    
     @Produces("application/json")
     @Operation(
-        method = "get",
         summary="Get a booking with ID",
-        operationId = "getBookingById",
-        responses={
+        operationId = "getBookingById")
+    @APIResponses(value={
             @APIResponse(
-                responseCode="200",
-                description="Booking retrieved",
-                content=@Content(
-                    schema=@Schema(
-                        implementation=Booking.class))),
+                    responseCode="200",
+                    description="Booking retrieved",
+                    content=@Content(
+                        schema=@Schema(
+                            implementation=Booking.class))),
             @APIResponse(
-                responseCode="404",
-                description="Booking not found")
-        })
+                    responseCode="404",
+                    description="Booking not found")
+    })
     public Response getBooking(
         @PathParam("id") int id){
             Booking booking = bookings.get(id);
@@ -197,20 +193,17 @@ public class BookingResource {
     @Path("{id}")
     @Consumes("application/json")
     @Produces("text/plain")
+    @APIResponse(
+            responseCode="200",
+            description="Booking updated"
+            )
+    @APIResponse(
+            responseCode="404",
+            description="Booking not found"
+            )
     @Operation(
-        method = "put",
         summary="Update a booking with ID",
-        operationId = "updateBookingId",
-        responses={
-            @APIResponse(
-                responseCode="200",
-                description="Booking updated"
-                ),
-            @APIResponse(
-                responseCode="404",
-                description="Booking not found"
-                )
-        })
+        operationId = "updateBookingId")
     public Response updateBooking(
         @PathParam("id") int id, Booking booking){
             if(bookings.get(id)!=null){
@@ -224,20 +217,17 @@ public class BookingResource {
 
     @DELETE
     @Path("{id}")
+    @APIResponse(
+            responseCode="200",
+            description="Booking deleted successfully."
+        )
+    @APIResponse(
+            responseCode="404",
+            description="Booking not found."
+        )
     @Operation(
-        method = "delete",
         summary="Delete a booking with ID",
-        operationId = "deleteBookingById",
-        responses={
-            @APIResponse(
-                responseCode="200",
-                description="Booking deleted successfully."
-            ),
-            @APIResponse(
-                responseCode="404",
-                description="Booking not found."
-            )
-        })
+        operationId = "deleteBookingById")
     @Produces("text/plain")
     public Response deleteBooking(
             @PathParam("id") int id){
diff --git a/tck/src/main/java/org/eclipse/microprofile/openapi/apps/airlines/resources/ReviewResource.java b/tck/src/main/java/org/eclipse/microprofile/openapi/apps/airlines/resources/ReviewResource.java
index c259df5..a77a0ae 100644
--- a/tck/src/main/java/org/eclipse/microprofile/openapi/apps/airlines/resources/ReviewResource.java
+++ b/tck/src/main/java/org/eclipse/microprofile/openapi/apps/airlines/resources/ReviewResource.java
@@ -40,6 +40,7 @@ import org.eclipse.microprofile.openapi.annotations.enums.SchemaType;
 import org.eclipse.microprofile.openapi.annotations.enums.SecuritySchemeType;
 import org.eclipse.microprofile.openapi.annotations.callbacks.Callback;
 import org.eclipse.microprofile.openapi.annotations.callbacks.Callbacks;
+import org.eclipse.microprofile.openapi.annotations.callbacks.CallbackOperation;
 import org.eclipse.microprofile.openapi.annotations.security.OAuthFlows;
 import org.eclipse.microprofile.openapi.annotations.security.OAuthFlow;
 import org.eclipse.microprofile.openapi.annotations.servers.Server;
@@ -51,6 +52,7 @@ import org.eclipse.microprofile.openapi.annotations.media.Schema;
 import org.eclipse.microprofile.openapi.annotations.parameters.RequestBody;
 import org.eclipse.microprofile.openapi.annotations.media.ExampleObject;
 import org.eclipse.microprofile.openapi.annotations.responses.APIResponse;
+import org.eclipse.microprofile.openapi.annotations.responses.APIResponses;
 import org.eclipse.microprofile.openapi.annotations.security.SecurityScheme;
 import org.eclipse.microprofile.openapi.annotations.servers.Servers;
 import org.eclipse.microprofile.openapi.annotations.tags.Tag;
@@ -123,12 +125,9 @@ public class ReviewResource {
         "Parkings", "female", 23, "nora@mail.com", "12-12-12", 1), 
         new Airline("Acme Air", "1-888-1234-567"), 7, "good"));
     }
+    
     @GET
-    @Operation(
-        operationId = "getAllReviews",
-        summary = "get all the reviews",
-        method = "get",
-        responses = @APIResponse(
+    @APIResponse(
             responseCode = "200",
             description = "successful operation",
             content = @Content(
@@ -140,6 +139,9 @@ public class ReviewResource {
             ),
             headers = @Header(ref="Request-Limit")
         )
+    @Operation(
+        operationId = "getAllReviews",
+        summary = "get all the reviews"
     )
     @Produces("application/json")
     public Response getAllReviews(){
@@ -148,21 +150,18 @@ public class ReviewResource {
 
     @GET
     @Path("{id}")
+    @APIResponse(
+            responseCode="200",
+            description="Review retrieved",
+            content=@Content(
+                schema=@Schema(
+                    implementation=Review.class)))
+    @APIResponse(
+            responseCode="404",
+            description="Review not found")
     @Operation(
         operationId = "getReviewById",
-        summary="Get a review with ID",
-        method= "get",
-        responses={
-            @APIResponse(
-                responseCode="200",
-                description="Review retrieved",
-                content=@Content(
-                    schema=@Schema(
-                        implementation=Review.class))),
-            @APIResponse(
-                responseCode="404",
-                description="Review not found")
-        }
+        summary="Get a review with ID"
     )
     @Produces("application/json")
     public Response getReviewById(
@@ -187,20 +186,19 @@ public class ReviewResource {
     @GET
     @Path("{user}")
     @Operation(
-        method = "get",
         operationId = "getReviewByUser",
-        summary="Get all reviews by user",
-        responses={
+        summary="Get all reviews by user")
+    @APIResponses(value={
             @APIResponse(
-                responseCode="200",
-                description="Review(s) retrieved",
-                content=@Content(
-                    schema=@Schema(
-                        implementation=Review.class))),
+                    responseCode="200",
+                    description="Review(s) retrieved",
+                    content=@Content(
+                        schema=@Schema(
+                            implementation=Review.class))),
             @APIResponse(
-                responseCode="404",
-                description="Review(s) not found")
-        })
+                    responseCode="404",
+                    description="Review(s) not found")
+    })
     @Produces("application/json")
     public Response getReviewByUser(
         @Parameter(
@@ -232,31 +230,26 @@ public class ReviewResource {
     @GET
     @Path("{airline}")
     @Operation(
-        method = "get",
         operationId = "getReviewByAirline",
-        summary="Get all reviews by airlines",
-        parameters = {
-            @Parameter(
-                name = "airline",
-                description = "name of the airlines for the reviews",
-                required = true,
-                in = ParameterIn.PATH,
-                content = @Content(
-                    examples = @ExampleObject(
-                        value = "Acme Air")),
-                example = "Acme Air")
-        },
-        responses={
-            @APIResponse(
-                responseCode="200",
-                description="Review(s) retrieved",
-                content=@Content(
-                    schema=@Schema(
-                        implementation=Review.class))),
-            @APIResponse(
-                responseCode="404",
-                description="Review(s) not found")
-        })
+        summary="Get all reviews by airlines")
+    @Parameter(
+            name = "airline",
+            description = "name of the airlines for the reviews",
+            required = true,
+            in = ParameterIn.PATH,
+            content = @Content(
+                examples = @ExampleObject(
+                    value = "Acme Air")),
+            example = "Acme Air")
+    @APIResponse(
+            responseCode="200",
+            description="Review(s) retrieved",
+            content=@Content(
+                schema=@Schema(
+                    implementation=Review.class)))
+    @APIResponse(
+            responseCode="404",
+            description="Review(s) not found")
     @Produces("application/json")
     public Response getReviewByAirline(
         @Parameter(
@@ -286,21 +279,18 @@ public class ReviewResource {
 
     @GET
     @Path("{user}/{airlines}")
+    @APIResponse(
+            responseCode="200",
+            description="Review(s) retrieved",
+            content=@Content(
+                schema=@Schema(
+                implementation=Review.class)))
+    @APIResponse(
+            responseCode="404",
+            description="Review(s) not found")
     @Operation(
-        method = "get",
         operationId = "getReviewByAirlineAndUser",
-        summary="Get all reviews for an airline by User",
-        responses={
-            @APIResponse(
-                responseCode="200",
-                description="Review(s) retrieved",
-                content=@Content(
-                    schema=@Schema(
-                    implementation=Review.class))),
-            @APIResponse(
-                responseCode="404",
-                description="Review(s) not found")
-        })
+        summary="Get all reviews for an airline by User")
     @Produces("application/json")
     public Response getReviewByAirlineAndUser(
         @Parameters(
@@ -346,8 +336,7 @@ public class ReviewResource {
         {@Callback(
             name = "testCallback",
             callbackUrlExpression="http://localhost:9080/oas3-airlines/reviews",
-            operation = @Operation(
-                operationId = "getAllReviews",
+            operations = @CallbackOperation(
                 summary = "Get all reviews",
                 method = "get",
                 responses = @APIResponse(
@@ -365,46 +354,44 @@ public class ReviewResource {
             )
         }
     )
+    @Tag(ref="Reviews")
+    @Servers(value={
+            @Server(url = "localhost:9080/{proxyPath}/reviews/id",
+                    description = "view of all the reviews",
+                    variables = { @ServerVariable(name = "proxyPath", description = "Base path of the proxy", defaultValue = "proxy") }),
+            @Server(url = "http://random.url/reviews", description = "random text")
+    })
+    @SecurityRequirement(
+            name = "reviewoauth2",
+            scopes = "write:reviews")
+    @APIResponse(
+            responseCode="201",
+            description="review created",
+            content = @Content(
+                    schema = @Schema(
+                            name= "id",
+                            description = "id of the new review",
+                            type = SchemaType.STRING)),
+            links = {
+                    @Link(
+                            name="Review",
+                            description="get the review that was added",
+                            operationId="getReviewById",
+                            server = @Server(
+                                    description = "endpoint for all the review related methods",
+                                    url = "http://localhost:9080/airlines/reviews/"),
+                                    parameters = @LinkParameter(
+                                            name = "reviewId",
+                                            expression = "$request.path.id")
+                            )
+            }
+            )
+    @RequestBody(
+            ref = "#/components/requestBodies/review"
+    )
     @Operation(
-        method = "post",
         summary="Create a Review",
-        operationId = "createReview",
-        tags = {"Reviews"},
-        servers = {
-                @Server(url = "localhost:9080/{proxyPath}/reviews/id",
-                        description = "view of all the reviews",
-                        variables = { @ServerVariable(name = "proxyPath", description = "Base path of the proxy", defaultValue = "proxy") }),
-                @Server(url = "http://random.url/reviews", description = "random text") },
-        security = @SecurityRequirement(
-                     name = "reviewoauth2",
-                     scopes = "write:reviews"),
-        responses={
-                    @APIResponse(
-                            responseCode="201",
-                            description="review created",
-                            content = @Content(
-                                    schema = @Schema(
-                                            name= "id",
-                                            description = "id of the new review",
-                                            type = SchemaType.STRING)),
-                            links = {
-                                    @Link(
-                                            name="Review",
-                                            description="get the review that was added",
-                                            operationId="getReviewById",
-                                            server = @Server(
-                                                    description = "endpoint for all the review related methods",
-                                                    url = "http://localhost:9080/airlines/reviews/"),
-                                                    parameters = @LinkParameter(
-                                                            name = "reviewId",
-                                                            expression = "$request.path.id")
-                                            )
-                            }
-                            )
-        },
-        requestBody = @RequestBody(
-                ref = "#/components/requestBodies/review"
-        )
+        operationId = "createReview"
     )
     @Consumes("application/json")
     @Produces("application/json")
@@ -415,20 +402,18 @@ public class ReviewResource {
 
     @DELETE
     @Path("{id}")
+    @APIResponse(
+            responseCode="200",
+            description="Review deleted"
+            )
+    @APIResponse(
+            responseCode="404",
+            description="Review not found"
+            )
     @Operation(
-        method = "delete",
         summary="Delete a Review with ID",
-        operationId = "deleteReview",
-        responses={
-            @APIResponse(
-                responseCode="200",
-                description="Review deleted"
-                ),
-            @APIResponse(
-                responseCode="404",
-                description="Review not found"
-                )
-        })
+        operationId = "deleteReview"
+        )
     @Produces("text/plain")
     public Response deleteReview(
             @PathParam("id") int id){
diff --git a/tck/src/main/java/org/eclipse/microprofile/openapi/apps/airlines/resources/UserResource.java b/tck/src/main/java/org/eclipse/microprofile/openapi/apps/airlines/resources/UserResource.java
index fcc1817..8d42a17 100644
--- a/tck/src/main/java/org/eclipse/microprofile/openapi/apps/airlines/resources/UserResource.java
+++ b/tck/src/main/java/org/eclipse/microprofile/openapi/apps/airlines/resources/UserResource.java
@@ -23,6 +23,7 @@ import org.eclipse.microprofile.openapi.annotations.media.Schema;
 import org.eclipse.microprofile.openapi.annotations.media.ExampleObject;
 import org.eclipse.microprofile.openapi.annotations.media.Encoding;
 import org.eclipse.microprofile.openapi.annotations.parameters.Parameter;
+import org.eclipse.microprofile.openapi.annotations.parameters.Parameters;
 import org.eclipse.microprofile.openapi.annotations.enums.ParameterIn;
 import org.eclipse.microprofile.openapi.annotations.enums.ParameterStyle;
 import org.eclipse.microprofile.openapi.annotations.responses.APIResponse;
@@ -86,129 +87,124 @@ public class UserResource {
                     description = "Unable to create this user record."
                 )
     })
-    @Operation(
-        method = "post",
-        summary = "Create user",
-        description = "This can only be done by the logged in user.",
-        operationId = "createUser",
-        requestBody = @RequestBody(
-            description = "Record of a new user to be created in the system.",
-            required = true,
-            content = @Content(
-                mediaType = "application/json",
-                schema = @Schema(
-                    name = "testUser",
-                    type = SchemaType.OBJECT,
-                    maxProperties = 1024,
-                    minProperties = 1,
-                    requiredProperties = { "id", "username", "password" },
-                    required = true, 
-                    implementation = User.class),
-                examples = @ExampleObject(
-                    name = "user",
-                    summary = "External user example",
-                    externalValue = "http://foo.bar/examples/user-example.json"
-                    ),
-                encoding = @Encoding(
-                    name = "email",
-                    contentType = "text/plain",
-                    style = "form",
-                    allowReserved = true,
-                    explode = true,
-                    headers = @Header(
-                        name = "testHeader"
-                    )
-                )
-            )
-        ),
-        parameters = {
-            @Parameter(
-                name = "id",
-                in = ParameterIn.QUERY,
-                description = "User id for the new user record to be created",
-                required = true,
-                allowReserved = true,
-                style = ParameterStyle.FORM,
-                schema = @Schema(type = SchemaType.INTEGER, format = "int32")
-            ),
+    @Parameters(value={
             @Parameter(
-                name = "userName",
-                in = ParameterIn.QUERY,
-                description = "Username for the new user record to be created",
-                required = true,
-                schema = @Schema(
-                    type = SchemaType.STRING,
-                    externalDocs = @ExternalDocumentation(
-                        description = "How to create good user names.",
-                        url = "http://exampleurl.com/usernames"
+                    name = "id",
+                    in = ParameterIn.QUERY,
+                    description = "User id for the new user record to be created",
+                    required = true,
+                    allowReserved = true,
+                    style = ParameterStyle.FORM,
+                    schema = @Schema(type = SchemaType.INTEGER, format = "int32")
+                ),
+                @Parameter(
+                    name = "userName",
+                    in = ParameterIn.QUERY,
+                    description = "Username for the new user record to be created",
+                    required = true,
+                    schema = @Schema(
+                        type = SchemaType.STRING,
+                        externalDocs = @ExternalDocumentation(
+                            description = "How to create good user names.",
+                            url = "http://exampleurl.com/usernames"
+                        )
                     )
-                )
-            ),
-            @Parameter(
-                name = "password",
-                in = ParameterIn.QUERY,
-                description = "User password for the new user record to be created",
-                required = true,
-                hidden = true,
-                schema = @Schema(
-                    type = SchemaType.STRING,
-                    externalDocs = @ExternalDocumentation(
-                        description = "How to create good passwords.",
-                        url = "http://exampleurl.com/passwords"
+                ),
+                @Parameter(
+                    name = "password",
+                    in = ParameterIn.QUERY,
+                    description = "User password for the new user record to be created",
+                    required = true,
+                    hidden = true,
+                    schema = @Schema(
+                        type = SchemaType.STRING,
+                        externalDocs = @ExternalDocumentation(
+                            description = "How to create good passwords.",
+                            url = "http://exampleurl.com/passwords"
+                        )
                     )
+                ),
+                @Parameter(
+                    name = "firstName",
+                    in = ParameterIn.QUERY,
+                    description = "User's first name for the new user record to be created",
+                    required = true,
+                    schema = @Schema(type = SchemaType.STRING)
+                ),
+                @Parameter(
+                    name = "lastName",
+                    in = ParameterIn.QUERY,
+                    description = "User's last name for the new user record to be created",
+                    style = ParameterStyle.FORM,
+                    required = true,
+                    schema = @Schema(type = SchemaType.STRING)
+                ),
+                @Parameter(
+                    name = "sex",
+                    in = ParameterIn.QUERY,
+                    description = "User's sex for the new user record to be created",
+                    required = true,
+                    style = ParameterStyle.FORM,
+                    schema = @Schema(type = SchemaType.STRING)
+                ),
+                @Parameter(
+                    name = "age",
+                    in = ParameterIn.QUERY,
+                    description = "User's age for the new user record to be created",
+                    required = true,
+                    schema = @Schema(type = SchemaType.INTEGER, format = "int64")
+                ),
+                @Parameter(
+                    name = "phone",
+                    in = ParameterIn.QUERY,
+                    description = "User phone number for the new user record to be created",
+                    required = true,
+                    schema = @Schema(type = SchemaType.STRING)
+                ),
+                @Parameter(
+                    name = "status",
+                    in = ParameterIn.QUERY,
+                    description = "User status for the new user record to be created",
+                    required = true,
+                    schema = @Schema(type = SchemaType.INTEGER)
                 )
-            ),
-            @Parameter(
-                name = "firstName",
-                in = ParameterIn.QUERY,
-                description = "User's first name for the new user record to be created",
-                required = true,
-                schema = @Schema(type = SchemaType.STRING)
-            ),
-            @Parameter(
-                name = "lastName",
-                in = ParameterIn.QUERY,
-                description = "User's last name for the new user record to be created",
-                style = ParameterStyle.FORM,
-                required = true,
-                schema = @Schema(type = SchemaType.STRING)
-            ),
-            @Parameter(
-                name = "sex",
-                in = ParameterIn.QUERY,
-                description = "User's sex for the new user record to be created",
-                required = true,
-                style = ParameterStyle.FORM,
-                schema = @Schema(type = SchemaType.STRING)
-            ),
-            @Parameter(
-                name = "age",
-                in = ParameterIn.QUERY,
-                description = "User's age for the new user record to be created",
-                required = true,
-                schema = @Schema(type = SchemaType.INTEGER, format = "int64")
-            ),
-            @Parameter(
-                name = "phone",
-                in = ParameterIn.QUERY,
-                description = "User phone number for the new user record to be created",
-                required = true,
-                schema = @Schema(type = SchemaType.STRING)
-            ),
-            @Parameter(
-                name = "status",
-                in = ParameterIn.QUERY,
-                description = "User status for the new user record to be created",
-                required = true,
-                schema = @Schema(type = SchemaType.INTEGER)
-            )
-        })
+    })
+    @Operation(
+        summary = "Create user",
+        description = "This can only be done by the logged in user.",
+        operationId = "createUser"  
+        )
     public Response createUser(
-        @Parameter(
-            description = "Created user object",
-            schema = @Schema(implementation = User.class),
-            required = true
-        ) User user) {
+            @RequestBody(
+                    description = "Record of a new user to be created in the system.",
+                    required = true,
+                    content = @Content(
+                        mediaType = "application/json",
+                        schema = @Schema(
+                            name = "testUser",
+                            type = SchemaType.OBJECT,
+                            maxProperties = 1024,
+                            minProperties = 1,
+                            requiredProperties = { "id", "username", "password" },
+                            required = true, 
+                            implementation = User.class),
+                        examples = @ExampleObject(
+                            name = "user",
+                            summary = "External user example",
+                            externalValue = "http://foo.bar/examples/user-example.json"
+                            ),
+                        encoding = @Encoding(
+                            name = "email",
+                            contentType = "text/plain",
+                            style = "form",
+                            allowReserved = true,
+                            explode = true,
+                            headers = @Header(
+                                name = "testHeader"
+                            )
+                        )
+                    )
+                ) User user) {
         userData.addUser(user);
         return Response.ok().entity("").build();
         }
@@ -217,47 +213,43 @@ public class UserResource {
     @Path("/createWithArray")
     @Tag(ref="user")
     @Tag(ref="create")
+    @Parameter(
+            name = "userArray",
+            in = ParameterIn.QUERY,
+            description = "An array of User objects to create records.",
+            required = true,
+            explode = Explode.FALSE,
+            content = @Content(
+                mediaType = "application/json",
+                schema = @Schema(
+                    type = SchemaType.ARRAY,
+                    implementation = User.class,
+                    nullable = true,
+                    writeOnly = true,
+                    minItems = 2
+                ),
+                encoding = @Encoding(
+                    name = "firstName",
+                    contentType = "text/plain",
+                    style = "form",
+                    allowReserved = true,
+                    explode = true
+                )
+            )
+        )
+    @APIResponse(
+            responseCode = "200",
+            description = "Successfully created list of users."
+        )
+    @APIResponse(
+            responseCode = "400",
+            description = "Unable to create list of users."
+        )
     @Operation(
-        method = "post",
         summary = "Creates list of users with given input array", //Array of User objects
-        operationId = "createUsersFromArray",
+        operationId = "createUsersFromArray"
         /* tags = {"user"}, //this operation intentionally doesn't have tags attribute, since above Tag ref should apply */
-        parameters = {
-            @Parameter(
-                name = "userArray",
-                in = ParameterIn.QUERY,
-                description = "An array of User objects to create records.",
-                required = true,
-                explode = Explode.FALSE,
-                content = @Content(
-                    mediaType = "application/json",
-                    schema = @Schema(
-                        type = SchemaType.ARRAY,
-                        implementation = User.class,
-                        nullable = true,
-                        writeOnly = true,
-                        minItems = 2
-                    ),
-                    encoding = @Encoding(
-                        name = "firstName",
-                        contentType = "text/plain",
-                        style = "form",
-                        allowReserved = true,
-                        explode = true
-                    )
-                )
-            )
-        },
-        responses = {
-            @APIResponse(
-                responseCode = "200",
-                description = "Successfully created list of users."
-            ),
-            @APIResponse(
-                responseCode = "400",
-                description = "Unable to create list of users."
-            )
-        })
+        )
     public Response createUsersWithArrayInput(
         @Parameter(
             description = "Array of user object",
@@ -273,21 +265,18 @@ public class UserResource {
     @Path("/createWithList")
     @Tag(ref="user")
     @Tags(refs="create")
+    @APIResponse(
+            responseCode = "200",
+            description = "Successfully created list of users."
+            )
+    @APIResponse(
+            responseCode = "400",
+            description = "Unable to create list of users."
+            )
     @Operation(
-        method = "post",
         summary = "Creates list of users with given input list", //List of User objects
-        operationId = "createUsersFromList",
-        tags = {"user"},
-        responses = {
-            @APIResponse(
-                responseCode = "200",
-                description = "Successfully created list of users."
-                ),
-            @APIResponse(
-                responseCode = "400",
-                description = "Unable to create list of users."
-                )
-        })
+        operationId = "createUsersFromList"
+        )
       public Response createUsersWithListInput(
             @Parameter(
                 description = "List of user object",
@@ -299,53 +288,54 @@ public class UserResource {
                 }
                 return Response.ok().entity("").build();
             }
+    
     @Path("/{username}")
       @PUT
+      @RequestBody(
+              name = "user",
+              description = "Record of a new user to be created in the system.",
+              content = @Content(
+                  mediaType = "application/json",
+                  schema = @Schema(implementation = User.class),
+                  examples = @ExampleObject(
+                      name = "user",
+                      summary = "Example user properties to update",
+                      value = "Properties to update in JSON format here"
+                  )
+              )
+          )
       @Operation(
-        method = "put",
         summary = "Update user",
         description = "This can only be done by the logged in user.",
-        operationId = "updateUser",
-        tags = {"user"},
-        requestBody = @RequestBody(
-            description = "Record of a new user to be created in the system.",
-            content = @Content(
-                mediaType = "application/json",
-                schema = @Schema(implementation = User.class),
-                examples = @ExampleObject(
-                    name = "user",
-                    summary = "Example user properties to update",
-                    value = "Properties to update in JSON format here"
-                )
-            )
-        ),
-        responses = {
+        operationId = "updateUser")
+    @APIResponses(value={
             @APIResponse(
-                responseCode = "200",
-                description = "User updated successfully",
-                content = @Content(
-                    schema = @Schema(
-                        name = "updatedUser",
-                        implementation = User.class
-                        ),
-                    encoding = @Encoding(
-                        name = "password",
-                        contentType = "text/plain",
-                        style = "form",
-                        allowReserved = true,
-                        explode = true
+                    responseCode = "200",
+                    description = "User updated successfully",
+                    content = @Content(
+                        schema = @Schema(
+                            name = "updatedUser",
+                            implementation = User.class
+                            ),
+                        encoding = @Encoding(
+                            name = "password",
+                            contentType = "text/plain",
+                            style = "form",
+                            allowReserved = true,
+                            explode = true
+                            )
                         )
-                    )
-            ),
-            @APIResponse(
-                responseCode = "400",
-                description = "Invalid user supplied"
-            ),
-            @APIResponse(
-                responseCode = "404",
-                description = "User not found"
-            )
-        })
+                ),
+                @APIResponse(
+                    responseCode = "400",
+                    description = "Invalid user supplied"
+                ),
+                @APIResponse(
+                    responseCode = "404",
+                    description = "User not found"
+                )
+    })
+    @Tag(ref="user")
     public Response updateUser(
         @Parameter(
             name = "username",
@@ -354,35 +344,30 @@ public class UserResource {
             required = true
             )
         @PathParam("username") String username,
-        @Parameter(
-            description = "Updated user object",
-            required = true) User user) {
+        User user) {
                 userData.addUser(user);
                 return Response.ok().entity("").build();
             }
 
       @DELETE
       @Path("/{username}")
+      @Tag(ref="user")
+      @APIResponse(
+              responseCode = "200",
+              description = "User deleted successfully"
+              )
+      @APIResponse(
+              responseCode = "400",
+              description = "Invalid username supplied"
+              )
+      @APIResponse(
+              responseCode = "404",
+              description = "User not found"
+              )
       @Operation(
-        method = "delete",
         summary = "Delete user",
         description = "This can only be done by the logged in user.",
-        operationId = "deleteUser",
-        tags = {"user"},
-        responses = {
-            @APIResponse(
-                responseCode = "200",
-                description = "User deleted successfully"
-                ),
-            @APIResponse(
-                responseCode = "400",
-                description = "Invalid username supplied"
-                ),
-            @APIResponse(
-                responseCode = "404",
-                description = "User not found"
-                )
-        })
+        operationId = "deleteUser")
     public Response deleteUser(
         @Parameter(
             name = "username",
@@ -401,32 +386,31 @@ public class UserResource {
 
     @GET
     @Path("/{username}")
-    @Operation(
-        method = "get",
-        summary = "Get user by user name",
-        operationId = "getUserByUserName",
-        tags = {"user"},
-        responses = {
-            @APIResponse(
-                responseCode = "200",
-                description = "Successfully retrieved user by user name.",
-                content = @Content(
-                    schema = @Schema(implementation = User.class)
-                )),
+    @Tag(ref="user")
+    @APIResponses(value={
             @APIResponse(
-                responseCode = "400",
-                description = "Invalid username supplied",
-                content = @Content(
+                    responseCode = "200",
+                    description = "Successfully retrieved user by user name.",
+                    content = @Content(
                         schema = @Schema(implementation = User.class)
-                )),
-            @APIResponse(
-                responseCode = "404",
-                description = "User not found",
-                        content = @Content(
-                                schema = @Schema(implementation = User.class)
-                        )
-                )
-                })
+                    )),
+                @APIResponse(
+                    responseCode = "400",
+                    description = "Invalid username supplied",
+                    content = @Content(
+                            schema = @Schema(implementation = User.class)
+                    )),
+                @APIResponse(
+                    responseCode = "404",
+                    description = "User not found",
+                            content = @Content(
+                                    schema = @Schema(implementation = User.class)
+                            )
+                    )
+    })
+    @Operation(
+        summary = "Get user by user name",
+        operationId = "getUserByUserName")
     public Response getUserByName(
         @Parameter(
             ref= "username"
@@ -443,50 +427,47 @@ public class UserResource {
 
     @GET
     @Path("/{id}")
-    @Operation(
-        method = "get",
-        summary = "Get user by id",
-        operationId = "getUserById",
-        tags = {"user"},
-        responses = {
-            @APIResponse(
-                responseCode = "200",
-                description = "Successfully retrieved user by id.",
-                content = @Content(
-                    schema = @Schema(implementation = User.class)),
-                links = { 
-                    @Link(
-                        name = "User name",
-                        description = "The username corresponding to provided user id",
-                        operationId = "getUserByName",
-                        parameters = @LinkParameter(
-                            name = "userId",
-                            expression = "$request.path.id")),
-                    @Link(
-                         name = "Review",
-                         description = "The reviews provided by user",
-                         operationRef = "/db/reviews/{userName}",
-                         parameters = @LinkParameter(
-                             name = "path.userName",
-                             expression = "$response.body#userName"),
-                         requestBody = "$request.path.id",
-                         server = @Server(url = "http://example.com"))
-                }
-                ),
-            @APIResponse(
-                responseCode = "400",
-                description = "Invalid id supplied",
+    @Tag(ref="user")
+    @APIResponse(
+            responseCode = "200",
+            description = "Successfully retrieved user by id.",
+            content = @Content(
+                schema = @Schema(implementation = User.class)),
+            links = { 
+                @Link(
+                    name = "User name",
+                    description = "The username corresponding to provided user id",
+                    operationId = "getUserByName",
+                    parameters = @LinkParameter(
+                        name = "userId",
+                        expression = "$request.path.id")),
+                @Link(
+                     name = "Review",
+                     description = "The reviews provided by user",
+                     operationRef = "/db/reviews/{userName}",
+                     parameters = @LinkParameter(
+                         name = "path.userName",
+                         expression = "$response.body#userName"),
+                     requestBody = "$request.path.id",
+                     server = @Server(url = "http://example.com"))
+            }
+            )
+    @APIResponse(
+            responseCode = "400",
+            description = "Invalid id supplied",
+            content = @Content(
+                schema = @Schema(implementation = User.class)
+            ))
+    @APIResponse(
+            responseCode = "404",
+            description = "User not found",
                 content = @Content(
                     schema = @Schema(implementation = User.class)
-                )),
-            @APIResponse(
-                responseCode = "404",
-                description = "User not found",
-                    content = @Content(
-                        schema = @Schema(implementation = User.class)
-                    )
                 )
-            })
+            )
+    @Operation(
+        summary = "Get user by id",
+        operationId = "getUserById")
     public Response getUserById(
         @Parameter(
             name = "id",
@@ -506,28 +487,25 @@ public class UserResource {
 
     @GET
     @Path("/login")
+    @Tag(ref="user")
+    @ExternalDocumentation(
+            description = "Policy on user security.",
+            url = "http://exampleurl.com/policy"
+    )
+    @APIResponse(
+            responseCode = "200",
+            description = "Successful user login.",
+            content = @Content(
+                schema = @Schema(implementation = User.class)
+            )
+        )
+    @APIResponse(
+            responseCode = "400",
+            description = "Invalid username/password supplied"
+            )
     @Operation(
-        method = "get",
         summary = "Logs user into the system",
-        operationId = "logInUser",
-        tags = {"user"},
-        externalDocs = @ExternalDocumentation(
-                description = "Policy on user security.",
-                url = "http://exampleurl.com/policy"
-        ),
-        responses = {
-            @APIResponse(
-                responseCode = "200",
-                description = "Successful user login.",
-                content = @Content(
-                    schema = @Schema(implementation = User.class)
-                )
-            ),
-            @APIResponse(
-                responseCode = "400",
-                description = "Invalid username/password supplied"
-                )
-            }
+        operationId = "logInUser"
     )
 
     @SecurityScheme(
@@ -561,15 +539,14 @@ public class UserResource {
                 responseCode = "200",
                 description = "Successful user logout."
                 )
-    @Operation(
-        method = "get",
-        summary = "Logs out current logged in user session",
-        operationId = "logOutUser",
-        /* tags = {"user"}, // intentionally removed to have a method with no tags */
-        externalDocs = @ExternalDocumentation(
+    @ExternalDocumentation(
             description = "Policy on user security.",
             url = "http://exampleurl.com/policy"
-            ))
+            )
+    @Operation(
+        summary = "Logs out current logged in user session",
+        operationId = "logOutUser"
+        /* tags = {"user"}, // intentionally removed to have a method with no tags */)
     public Response logoutUser() {
     return Response.ok().entity("").build();
     }
diff --git a/tck/src/main/java/org/eclipse/microprofile/openapi/apps/petstore/resource/PetResource.java b/tck/src/main/java/org/eclipse/microprofile/openapi/apps/petstore/resource/PetResource.java
index 0cf0496..c7ccff4 100644
--- a/tck/src/main/java/org/eclipse/microprofile/openapi/apps/petstore/resource/PetResource.java
+++ b/tck/src/main/java/org/eclipse/microprofile/openapi/apps/petstore/resource/PetResource.java
@@ -32,6 +32,8 @@ import org.eclipse.microprofile.openapi.annotations.media.Schema;
 import org.eclipse.microprofile.openapi.annotations.parameters.RequestBody;
 import org.eclipse.microprofile.openapi.annotations.media.ExampleObject;
 import org.eclipse.microprofile.openapi.annotations.responses.APIResponse;
+import org.eclipse.microprofile.openapi.annotations.responses.APIResponses;
+import org.eclipse.microprofile.openapi.annotations.callbacks.CallbackOperation;
 
 import org.eclipse.microprofile.openapi.apps.petstore.data.PetData;
 import org.eclipse.microprofile.openapi.apps.petstore.model.Pet;
@@ -104,32 +106,31 @@ public class PetResource {
 
     @GET
     @Path("/{petId}")
+    @APIResponses(value={
+            @APIResponse(
+                    responseCode = "400",
+                    description = "Invalid ID supplied",
+                    content = @Content(
+                        mediaType = "none")
+                ),
+                @APIResponse(
+                    responseCode = "404",
+                    description = "Pet not found",
+                    content = @Content(
+                        mediaType = "none")
+                ),
+                @APIResponse(
+                    responseCode = "200",
+                    content = @Content(
+                        mediaType = "application/json",
+                        schema = @Schema(type = SchemaType.ARRAY, implementation = Pet.class, 
+                          oneOf = { Cat.class, Dog.class, Lizard.class }, 
+                          readOnly = true))
+                )
+    })
     @Operation(
-            method = "GET",
             summary = "Find pet by ID",
-            description = "Returns a pet when ID is less than or equal to 10",
-            responses = {
-                    @APIResponse(
-                        responseCode = "400",
-                        description = "Invalid ID supplied",
-                        content = @Content(
-                            mediaType = "none")
-                    ),
-                    @APIResponse(
-                        responseCode = "404",
-                        description = "Pet not found",
-                        content = @Content(
-                            mediaType = "none")
-                    ),
-                    @APIResponse(
-                        responseCode = "200",
-                        content = @Content(
-                            mediaType = "application/json",
-                            schema = @Schema(type = SchemaType.ARRAY, implementation = Pet.class, 
-                              oneOf = { Cat.class, Dog.class, Lizard.class }, 
-                              readOnly = true))
-                    )
-            }
+            description = "Returns a pet when ID is less than or equal to 10"
     )
     public Response getPetById(
         @Parameter(
@@ -157,22 +158,21 @@ public class PetResource {
 
     @GET
     @Path("/{petId}/download")
+    @APIResponses(value={
+            @APIResponse(
+                    responseCode = "400",
+                    description = "Invalid ID supplied",
+                    content = @Content(mediaType = "none")
+                ),
+                @APIResponse(
+                    responseCode = "404",
+                    description = "Pet not found",
+                    content = @Content(mediaType = "none")
+                )
+    })
     @Operation(
-        method = "GET",
         summary = "Find pet by ID and download it",
-        description = "Returns a pet when ID is less than or equal to 10",
-        responses = {
-            @APIResponse(
-                responseCode = "400",
-                description = "Invalid ID supplied",
-                content = @Content(mediaType = "none")
-            ),
-            @APIResponse(
-                responseCode = "404",
-                description = "Pet not found",
-                content = @Content(mediaType = "none")
-            )
-        }
+        description = "Returns a pet when ID is less than or equal to 10"
     )
     public Response downloadFile(
         @Parameter(
@@ -205,24 +205,23 @@ public class PetResource {
 
     @DELETE
     @Path("/{petId}")
-    @Operation(
-        method = "DELETE",
-        summary = "Deletes a pet by ID",
-        description = "Returns a pet when ID is less than or equal to 10",
-        security = @SecurityRequirement(
+    @SecurityRequirement(
             name = "petsOAuth2",
             scopes = "write:pets"
-        ),
-        responses = {
-            @APIResponse(
-                responseCode = "400",
-                description = "Invalid ID supplied"
-            ),
-            @APIResponse(
-                responseCode = "404",
-                description = "Pet not found"
             )
-        }
+    @APIResponses(value = {
+            @APIResponse(
+                    responseCode = "400",
+                    description = "Invalid ID supplied"
+                ),
+                @APIResponse(
+                    responseCode = "404",
+                    description = "Pet not found"
+                )
+    })
+    @Operation(
+        summary = "Deletes a pet by ID",
+        description = "Returns a pet when ID is less than or equal to 10"
     )
     public Response deletePet(
         @Parameter(
@@ -251,23 +250,18 @@ public class PetResource {
     @POST
     @Consumes({"application/json", "application/xml"})
     @Produces({"application/json", "application/xml"})
-    @Operation(
-        method = "POST",
-        summary = "Add pet to store",
-        description = "Add a new pet to the store",
-        security = @SecurityRequirement(
+    @SecurityRequirement(
             name = "petsApiKey"
-        ),
-        responses = {
-            @APIResponse(
-                responseCode = "400",
-                description = "Invalid input",
-                content = @Content(
-                    mediaType = "application/json",
-                    schema = @Schema(implementation = ApiResponse.class))
-            )
-        },
-        requestBody = @RequestBody(
+        )
+    @APIResponse(
+            responseCode = "400",
+            description = "Invalid input",
+            content = @Content(
+                mediaType = "application/json",
+                schema = @Schema(implementation = ApiResponse.class))
+        )
+    @RequestBody(
+            name="pet",
             content = @Content(
                 mediaType = "application/json",
                 schema = @Schema(implementation = Pet.class), 
@@ -275,43 +269,40 @@ public class PetResource {
             required = true,
             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(
-        @Parameter(
-            name ="addPet",
-            description = "Pet to add",
-            required = true,
-            schema = @Schema(implementation = Pet.class)) Pet pet) {
+    public Response addPet(Pet pet) {
                 Pet updatedPet = petData.addPet(pet);
                 return Response.ok().entity(updatedPet).build();
             }
 
     @PUT
     @Consumes({"application/json", "application/xml"})
-    @Operation(
-        method = "PUT",
-        summary = "Update an existing pet",
-        description = "Update an existing pet with the given new attributes",
-        security = @SecurityRequirement(
+    @SecurityRequirement(
             name = "petsHttp"
-        ),
-        responses = {
-            @APIResponse(
-                responseCode = "400",
-                description = "Invalid ID supplied",
-                content = @Content(mediaType = "application/json")
-            ),
-            @APIResponse(
-                responseCode = "404",
-                description = "Pet not found",
-                content = @Content(mediaType = "application/json")
-            ),
+        )
+    @APIResponses(value={
             @APIResponse(
-                responseCode = "405",
-                description = "Validation exception",
-                content = @Content(mediaType = "application/json")
-            )
-        }
+                    responseCode = "400",
+                    description = "Invalid ID supplied",
+                    content = @Content(mediaType = "application/json")
+                ),
+                @APIResponse(
+                    responseCode = "404",
+                    description = "Pet not found",
+                    content = @Content(mediaType = "application/json")
+                ),
+                @APIResponse(
+                    responseCode = "405",
+                    description = "Validation exception",
+                    content = @Content(mediaType = "application/json")
+                )
+    })
+    @Operation(
+        summary = "Update an existing pet",
+        description = "Update an existing pet with the given new attributes"
     )
     public Response updatePet(
         @Parameter(
@@ -325,23 +316,20 @@ public class PetResource {
 
     @GET
     @Path("/findByStatus")
+    @APIResponse(
+            responseCode = "400",
+            description = "Invalid status value",
+            content = @Content(mediaType = "none")
+        )
+    @APIResponse(
+            responseCode = "200",
+            content = @Content(
+                mediaType = "application/json",
+                schema = @Schema(type = SchemaType.ARRAY, implementation = Pet.class))
+            )
     @Operation(
-        method = "GET",
         summary = "Finds Pets by status",
-        description = "Find all the Pets with the given status; Multiple status values can be provided with comma seperated strings",
-        responses = {
-            @APIResponse(
-                responseCode = "400",
-                description = "Invalid status value",
-                content = @Content(mediaType = "none")
-            ),
-            @APIResponse(
-                responseCode = "200",
-                content = @Content(
-                    mediaType = "application/json",
-                    schema = @Schema(type = SchemaType.ARRAY, implementation = Pet.class))
-                )
-        }
+        description = "Find all the Pets with the given status; Multiple status values can be provided with comma seperated strings"
     )
     @Extension(name = "x-mp-method1", value = "true")
     @Extensions( { @Extension(name = "x-mp-method2", value = "true"), @Extension(value = "false", name = "x-mp-method3") } )
@@ -381,10 +369,9 @@ public class PetResource {
     @Callback(
         name = "tagsCallback",
         callbackUrlExpression = "http://petstoreapp.com/pet",
-        operation = @Operation(
+        operations = @CallbackOperation(
             method = "GET",
             summary = "Finds Pets by tags",
-            deprecated = true,
             description = "Find Pets by tags; Muliple tags can be provided with comma seperated strings. Use tag1, tag2, tag3 for testing.",
             responses = {
                 @APIResponse(
@@ -418,16 +405,13 @@ public class PetResource {
     @POST
     @Path("/{petId}")
     @Consumes({MediaType.APPLICATION_FORM_URLENCODED})
+    @APIResponse(
+            responseCode = "405",
+            description = "Validation exception",
+            content = @Content(mediaType = "none")
+        )
     @Operation(
-        method = "POST",
-        summary = "Updates a pet in the store with form data",
-        responses = {
-            @APIResponse(
-                responseCode = "405",
-                description = "Validation exception",
-                content = @Content(mediaType = "none")
-            )
-        }
+        summary = "Updates a pet in the store with form data"
     )
     public Response updatePetWithForm (
         @Parameter(
diff --git a/tck/src/main/java/org/eclipse/microprofile/openapi/apps/petstore/resource/PetStoreResource.java b/tck/src/main/java/org/eclipse/microprofile/openapi/apps/petstore/resource/PetStoreResource.java
index aa735a1..df4ab80 100644
--- a/tck/src/main/java/org/eclipse/microprofile/openapi/apps/petstore/resource/PetStoreResource.java
+++ b/tck/src/main/java/org/eclipse/microprofile/openapi/apps/petstore/resource/PetStoreResource.java
@@ -78,16 +78,13 @@ public class PetStoreResource {
     @GET
     @Path("/inventory")
     @Produces({"application/json", "application/xml"})
+    @APIResponse(
+            responseCode = "200", 
+            description = "successful operation"
+        )
     @Operation(
-        method = "get",
         summary = "Returns pet inventories by status", 
-        description = "Returns a map of status codes to quantities", 
-        responses = {
-            @APIResponse(
-                responseCode = "200", 
-                description = "successful operation"
-            )
-        }
+        description = "Returns a map of status codes to quantities"
     )
     public java.util.Map<String, Integer> getInventory() {
         return petData.getInventoryByStatus();
@@ -96,39 +93,36 @@ public class PetStoreResource {
     @GET
     @Path("/order/{orderId}")
     @Operation(
-        method = "get",
         summary = "Find purchase order by ID",
-        description = "For valid response try integer IDs with value between the integers of 1 and 10. Other values will generated exceptions",
-        responses = { 
-            @APIResponse(
-                responseCode = "200", 
-                description = "successful operation",
-                content = @Content(
-                    schema = @Schema(implementation = Order.class, 
-                      allOf = { Order.class, Pet.class},
-                      not = BadOrder.class )
-                )
-            ),
-            @APIResponse(
-                responseCode = "400", 
-                description = "Invalid ID supplied",
-                content = @Content(
-                    schema = @Schema(implementation = Order.class,
-                      hidden = true)
-                )
-            ),
-            @APIResponse(
-                responseCode = "404", 
-                description = "Order not found",
-                content = @Content(
-                    schema = @Schema(implementation = Order.class, 
-                      anyOf = { Order.class, BadOrder.class},
-                      discriminatorProperty = "id", 
-                      discriminatorMapping = @DiscriminatorMapping(value = "0", schema = BadOrder.class) )
-                )
-            )
-        }
+        description = "For valid response try integer IDs with value between the integers of 1 and 10. Other values will generated exceptions"
     )
+    @APIResponse(
+            responseCode = "200", 
+            description = "successful operation",
+            content = @Content(
+                schema = @Schema(implementation = Order.class, 
+                  allOf = { Order.class, Pet.class},
+                  not = BadOrder.class )
+            )
+        )
+    @APIResponse(
+            responseCode = "400", 
+            description = "Invalid ID supplied",
+            content = @Content(
+                schema = @Schema(implementation = Order.class,
+                  hidden = true)
+            )
+        )
+    @APIResponse(
+            responseCode = "404", 
+            description = "Order not found",
+            content = @Content(
+                schema = @Schema(implementation = Order.class, 
+                  anyOf = { Order.class, BadOrder.class},
+                  discriminatorProperty = "id", 
+                  discriminatorMapping = @DiscriminatorMapping(value = "0", schema = BadOrder.class) )
+            )
+        )
     public Response getOrderById(
         @Parameter(
             name = "orderId",
@@ -153,19 +147,16 @@ public class PetStoreResource {
     @POST
     @Path("/order")
     @Operation(
-        method = "post",
-        summary = "Place an order for a pet",
-        responses = {
-            @APIResponse(
-                responseCode = "200", 
-                description = "successful operation"
-            ),
-            @APIResponse(
-                responseCode = "400", 
-                description = "Invalid Order"
-            ) 
-        }
+        summary = "Place an order for a pet"
     )
+    @APIResponse(
+            responseCode = "200", 
+            description = "successful operation"
+        )
+    @APIResponse(
+            responseCode = "400", 
+            description = "Invalid Order"
+            ) 
     public Order placeOrder(
         @Parameter(
             description = "order placed for purchasing the pet",
@@ -178,20 +169,17 @@ public class PetStoreResource {
 
     @DELETE
     @Path("/order/{orderId}")
+    @APIResponse(
+            responseCode = "400", 
+            description = "Invalid ID supplied"
+            )
+    @APIResponse(
+            responseCode = "404", 
+            description = "Order not found"
+            ) 
     @Operation(
-        method = "delete",
         summary = "Delete purchase order by ID",
-        description = "For valid response try integer IDs with positive integer value. Negative or non-integer values will generate API errors",
-        responses = { 
-            @APIResponse(
-                responseCode = "400", 
-                description = "Invalid ID supplied"
-                ),
-            @APIResponse(
-                responseCode = "404", 
-                description = "Order not found"
-                ) 
-        }
+        description = "For valid response try integer IDs with positive integer value. Negative or non-integer values will generate API errors"
     )
     public Response deleteOrder(
         @Parameter(
diff --git a/tck/src/main/java/org/eclipse/microprofile/openapi/apps/petstore/resource/UserResource.java b/tck/src/main/java/org/eclipse/microprofile/openapi/apps/petstore/resource/UserResource.java
index 0879150..7d647dd 100644
--- a/tck/src/main/java/org/eclipse/microprofile/openapi/apps/petstore/resource/UserResource.java
+++ b/tck/src/main/java/org/eclipse/microprofile/openapi/apps/petstore/resource/UserResource.java
@@ -17,6 +17,7 @@ import org.eclipse.microprofile.openapi.annotations.Operation;
 import org.eclipse.microprofile.openapi.annotations.media.Schema;
 import org.eclipse.microprofile.openapi.annotations.parameters.Parameter;
 import org.eclipse.microprofile.openapi.annotations.responses.APIResponse;
+import org.eclipse.microprofile.openapi.annotations.responses.APIResponses;
 import org.eclipse.microprofile.openapi.annotations.media.Content;
 import org.eclipse.microprofile.openapi.annotations.enums.SecuritySchemeIn;
 import org.eclipse.microprofile.openapi.annotations.enums.SchemaType;
@@ -75,15 +76,12 @@ public class UserResource {
     static UserData userData = new UserData();
 
     @POST
+    @APIResponse(
+            description = "successful operation"
+        )
     @Operation(
-        method = "post",
         summary = "Create user",
-        description = "This can only be done by the logged in user.",
-        responses = {
-            @APIResponse(
-                description = "successful operation"
-            )
-        }
+        description = "This can only be done by the logged in user."
     )
     @SecurityRequirements(
         value = {
@@ -110,14 +108,11 @@ public class UserResource {
 
     @POST
     @Path("/createWithArray")
+    @APIResponse(
+            description = "successful operation"
+        )
     @Operation(
-        method = "post",
-        summary = "Creates list of users with given input array",
-        responses = {
-            @APIResponse(
-                description = "successful operation"
-            )
-        }
+        summary = "Creates list of users with given input array"
     )
     public Response createUsersWithArrayInput(
         @Parameter(
@@ -132,14 +127,11 @@ public class UserResource {
 
     @POST
     @Path("/createWithList")
+    @APIResponse(
+            description = "successful operation"
+        )
     @Operation(
-        method = "post",
-        summary = "Creates list of users with given input array",
-        responses = {
-            @APIResponse(
-                description = "successful operation"
-            )
-        }
+        summary = "Creates list of users with given input array"
     )
     public Response createUsersWithListInput(
         @Parameter(
@@ -153,20 +145,17 @@ public class UserResource {
 
     @PUT
     @Path("/{username}")
+    @APIResponse(
+            responseCode = "400",
+            description = "Invalid user supplied"
+        )
+    @APIResponse(
+            responseCode = "404",
+            description = "User not found"
+        )
     @Operation(
-        method = "put",
         summary = "Updated user",
-        description = "This can only be done by the logged in user.",
-        responses = {
-            @APIResponse(
-                responseCode = "400",
-                description = "Invalid user supplied"
-            ),
-            @APIResponse(
-                responseCode = "404",
-                description = "User not found"
-            )
-        }
+        description = "This can only be done by the logged in user."
     )
     @SecurityRequirementsSet(
         value = {
@@ -195,20 +184,19 @@ public class UserResource {
 
     @DELETE
     @Path("/{username}")
+    @APIResponses(value={
+            @APIResponse(
+                    responseCode = "400",
+                    description = "Invalid username supplied"
+                ),
+                @APIResponse(
+                    responseCode = "404",
+                    description = "User not found"
+                )
+    })
     @Operation(
-        method = "delete",
         summary = "Delete user",
-        description = "This can only be done by the logged in user.",
-        responses = {
-            @APIResponse(
-                responseCode = "400",
-                description = "Invalid username supplied"
-            ),
-            @APIResponse(
-                responseCode = "404",
-                description = "User not found"
-            )
-        }
+        description = "This can only be done by the logged in user."
     )
     public Response deleteUser(
         @Parameter(
@@ -228,32 +216,31 @@ public class UserResource {
 
     @GET
     @Path("/{username}")
-    @Operation(
-        method = "get",
-        summary = "Get user by user name",
-        responses = {
+    @APIResponses(value={
             @APIResponse(
-                responseCode = "200",
-                description = "successful operation",
-                content = @Content(
-                    schema = @Schema(implementation = User.class)
-                )
-            ),
+                    responseCode = "200",
+                    description = "successful operation",
+                    content = @Content(
+                        schema = @Schema(implementation = User.class)
+                    )
+                ),
             @APIResponse(
-                responseCode = "400",
-                description = "Invalid username supplied",
-                content = @Content(
-                    schema = @Schema(implementation = User.class)
-                )
-            ),
+                    responseCode = "400",
+                    description = "Invalid username supplied",
+                    content = @Content(
+                        schema = @Schema(implementation = User.class)
+                    )
+                ),
             @APIResponse(
-                responseCode = "404",
-                description = "User not found",
-                content = @Content(
-                    schema = @Schema(implementation = User.class)
+                    responseCode = "404",
+                    description = "User not found",
+                    content = @Content(
+                        schema = @Schema(implementation = User.class)
+                    )
                 )
-            )
-        }
+    })
+    @Operation(
+        summary = "Get user by user name"
     )
     public Response getUserByName(
         @Parameter(
@@ -274,25 +261,22 @@ public class UserResource {
 
     @GET
     @Path("/login")
-    @Operation(
-        method = "get",
-        summary = "Logs user into the system",
-        responses = {
-            @APIResponse(
-                responseCode = "200",
-                description = "successful operation",
-                content = @Content(
-                    schema = @Schema(implementation = String.class)
-                )
-            ),
-            @APIResponse(
-                responseCode = "400",
-                description = "Invalid username/password supplied",
-                content = @Content(
-                    schema = @Schema(implementation = String.class)
-                )
+    @APIResponse(
+            responseCode = "200",
+            description = "successful operation",
+            content = @Content(
+                schema = @Schema(implementation = String.class)
             )
-        }
+        )
+    @APIResponse(
+            responseCode = "400",
+            description = "Invalid username/password supplied",
+            content = @Content(
+                schema = @Schema(implementation = String.class)
+            )
+        )
+    @Operation(
+        summary = "Logs user into the system"
     )
     public Response loginUser(
         @Parameter(
@@ -315,14 +299,11 @@ public class UserResource {
 
     @GET
     @Path("/logout")
+    @APIResponse(
+            description = "successful operation"
+        )
     @Operation(
-        method = "get",
-        summary = "Logs out current logged in user session",
-        responses = {
-            @APIResponse(
-                description = "successful operation"
-            )
-        }
+        summary = "Logs out current logged in user session"
     )
     public Response logoutUser() {
         return Response.ok().entity("").build();


Test patch:
diff --git a/tck/src/main/java/org/eclipse/microprofile/openapi/tck/ModelConstructionTest.java b/tck/src/main/java/org/eclipse/microprofile/openapi/tck/ModelConstructionTest.java
index cd941bf..b696131 100644
--- a/tck/src/main/java/org/eclipse/microprofile/openapi/tck/ModelConstructionTest.java
+++ b/tck/src/main/java/org/eclipse/microprofile/openapi/tck/ModelConstructionTest.java
@@ -162,52 +162,7 @@ public class ModelConstructionTest {
     
     @Test
     public void componentsTest() {
-        final Components c = processConstructible(Components.class);
-        
-        final String callbackKey = "myCallback";
-        final Callback callbackValue = createConstructibleInstance(Callback.class);
-        checkSameObject(c, c.addCallback(callbackKey, callbackValue));
-        checkMapEntry(c.getCallbacks(), callbackKey, callbackValue);
-        
-        final String exampleKey = "myExample";
-        final Example exampleValue = createConstructibleInstance(Example.class);
-        checkSameObject(c, c.addExample(exampleKey, exampleValue));
-        checkMapEntry(c.getExamples(), exampleKey, exampleValue);
-        
-        final String headerKey = "myHeader";
-        final Header headerValue = createConstructibleInstance(Header.class);
-        checkSameObject(c, c.addHeader(headerKey, headerValue));
-        checkMapEntry(c.getHeaders(), headerKey, headerValue);
-        
-        final String linkKey = "myLink";
-        final Link linkValue = createConstructibleInstance(Link.class);
-        checkSameObject(c, c.addLink(linkKey, linkValue));
-        checkMapEntry(c.getLinks(), linkKey, linkValue);
-        
-        final String parameterKey = "myParameter";
-        final Parameter<?> parameterValue = createConstructibleInstance(CookieParameter.class);
-        checkSameObject(c, c.addParameter(parameterKey, parameterValue));
-        checkMapEntry(c.getParameters(), parameterKey, parameterValue);
-        
-        final String requestBodyKey = "myRequestBody";
-        final RequestBody requestBodyValue = createConstructibleInstance(RequestBody.class);
-        checkSameObject(c, c.addRequestBody(requestBodyKey, requestBodyValue));
-        checkMapEntry(c.getRequestBodies(), requestBodyKey, requestBodyValue);
-        
-        final String responseKey = "myResponse";
-        final APIResponse responseValue = createConstructibleInstance(APIResponse.class);
-        checkSameObject(c, c.addResponse(responseKey, responseValue));
-        checkMapEntry(c.getResponses(), responseKey, responseValue);
-        
-        final String schemaKey = "mySchema";
-        final Schema schemaValue = createConstructibleInstance(Schema.class);
-        checkSameObject(c, c.addSchema(schemaKey, schemaValue));
-        checkMapEntry(c.getSchemas(), schemaKey, schemaValue);
-        
-        final String securitySchemeKey = "mySecurityScheme";
-        final SecurityScheme securitySchemeValue = createConstructibleInstance(SecurityScheme.class);
-        checkSameObject(c, c.addSecurityScheme(securitySchemeKey, securitySchemeValue));
-        checkMapEntry(c.getSecuritySchemes(), securitySchemeKey, securitySchemeValue);
+        processConstructible(Components.class);
     }
     
     @Test
@@ -217,87 +172,27 @@ public class ModelConstructionTest {
     
     @Test
     public void openAPITest() {
-        final OpenAPI o = processConstructible(OpenAPI.class);
-        
-        final SecurityRequirement sr = createConstructibleInstance(SecurityRequirement.class);
-        checkSameObject(o, o.addSecurityRequirement(sr));
-        checkListEntry(o.getSecurity(), sr);
-        
-        final Server s = createConstructibleInstance(Server.class);
-        checkSameObject(o, o.addServer(s));
-        checkListEntry(o.getServers(), s);
-        
-        final Tag t = createConstructibleInstance(Tag.class);
-        checkSameObject(o, o.addTag(t));
-        checkListEntry(o.getTags(), t);
+        processConstructible(OpenAPI.class);
     }
     
     @Test
     public void operationTest() {
-        final Operation o = processConstructible(Operation.class);
-        
-        final Parameter<?> p = createConstructibleInstance(CookieParameter.class);
-        checkSameObject(o, o.addParameter(p));
-        checkListEntry(o.getParameters(), p);
-        
-        final SecurityRequirement sr = createConstructibleInstance(SecurityRequirement.class);
-        checkSameObject(o, o.addSecurityRequirement(sr));
-        checkListEntry(o.getSecurity(), sr);
-        
-        final Server s = createConstructibleInstance(Server.class);
-        checkSameObject(o, o.addServer(s));
-        checkListEntry(o.getServers(), s);
-        
-        final String tag = new String("myTag");
-        checkSameObject(o, o.addTag(tag));
-        checkListEntry(o.getTags(), tag);
+        processConstructible(Operation.class);
     }
     
     @Test
     public void pathItemTest() {
-        final PathItem pi = processConstructible(PathItem.class);
-        
-        final Parameter<?> p = createConstructibleInstance(CookieParameter.class);
-        checkSameObject(pi, pi.addParameter(p));
-        checkListEntry(pi.getParameters(), p);
-        
-        final Server s = createConstructibleInstance(Server.class);
-        checkSameObject(pi, pi.addServer(s));
-        checkListEntry(pi.getServers(), s);
+        processConstructible(PathItem.class);
     }
     
     @Test
     public void pathsTest() {
-        final Paths p = processConstructible(Paths.class);
-        
-        final String pathItemKey = "myPathItem";
-        final PathItem pathItemValue = createConstructibleInstance(PathItem.class);
-        checkSameObject(p, p.addPathItem(pathItemKey, pathItemValue));
-        checkMapEntry(p, pathItemKey, pathItemValue);
-        
-        final String pathItemKey2 = "myPathItem2";
-        final PathItem pathItemValue2 = createConstructibleInstance(PathItem.class);
-        Assert.assertNull("No previous mapping expected.", p.put(pathItemKey2, pathItemValue2));
-        checkMapEntry(p, pathItemKey2, pathItemValue2);
-        
-        Assert.assertEquals("The map is expected to contain two entries.", 2, p.size());
+        processConstructible(Paths.class);
     }
     
     @Test
     public void callbackTest() {
-        final Callback c = processConstructible(Callback.class);
-        
-        final String pathItemKey = "myPathItem";
-        final PathItem pathItemValue = createConstructibleInstance(PathItem.class);
-        checkSameObject(c, c.addPathItem(pathItemKey, pathItemValue));
-        checkMapEntry(c, pathItemKey, pathItemValue);
-        
-        final String pathItemKey2 = "myPathItem2";
-        final PathItem pathItemValue2 = createConstructibleInstance(PathItem.class);
-        Assert.assertNull("No previous mapping expected.", c.put(pathItemKey2, pathItemValue2));
-        checkMapEntry(c, pathItemKey2, pathItemValue2);
-        
-        Assert.assertEquals("The map is expected to contain two entries.", 2, c.size());
+        processConstructible(Callback.class);
     }
     
     @Test
@@ -307,12 +202,7 @@ public class ModelConstructionTest {
     
     @Test
     public void headerTest() {
-        final Header h = processConstructible(Header.class);
-        
-        final String exampleKey = "myExample";
-        final Example exampleValue = createConstructibleInstance(Example.class);
-        checkSameObject(h, h.addExample(exampleKey, exampleValue));
-        checkMapEntry(h.getExamples(), exampleKey, exampleValue);
+        processConstructible(Header.class);
     }
     
     @Test
@@ -332,39 +222,17 @@ public class ModelConstructionTest {
     
     @Test
     public void linkTest() {
-        final Link l = processConstructible(Link.class);
-        
-        final String parameterKey = "myParameter";
-        final Parameter<?> parameterValue = createConstructibleInstance(CookieParameter.class);
-        checkSameObject(l, l.addParameter(parameterKey, parameterValue));
-        checkMapEntry(l.getParameters(), parameterKey, parameterValue);
+        processConstructible(Link.class);
     }
     
     @Test
     public void contentTest() {
-        final Content c = processConstructible(Content.class);
-        
-        final String mediaTypeKey = "myPathItem";
-        final MediaType mediaTypeValue = createConstructibleInstance(MediaType.class);
-        checkSameObject(c, c.addMediaType(mediaTypeKey, mediaTypeValue));
-        checkMapEntry(c, mediaTypeKey, mediaTypeValue);
-        
-        final String mediaTypeKey2 = "myPathItem2";
-        final MediaType mediaTypeValue2 = createConstructibleInstance(MediaType.class);
-        Assert.assertNull("No previous mapping expected.", c.put(mediaTypeKey2, mediaTypeValue2));
-        checkMapEntry(c, mediaTypeKey2, mediaTypeValue2);
-        
-        Assert.assertEquals("The map is expected to contain two entries.", 2, c.size());
+        processConstructible(Content.class);
     }
     
     @Test
     public void discriminatorTest() {
-        final Discriminator d = processConstructible(Discriminator.class);
-        
-        final String key = "myKey";
-        final String value = new String("myValue");
-        checkSameObject(d, d.addMapping(key, value));
-        checkMapEntry(d.getMapping(), key, value);
+        processConstructible(Discriminator.class);
     }
     
     @Test
@@ -374,47 +242,12 @@ public class ModelConstructionTest {
     
     @Test
     public void mediaTypeTest() {
-        final MediaType mt = processConstructible(MediaType.class);
-        
-        final String encodingKey = "myEncoding";
-        final Encoding encodingValue = createConstructibleInstance(Encoding.class);
-        checkSameObject(mt, mt.addEncoding(encodingKey, encodingValue));
-        checkMapEntry(mt.getEncoding(), encodingKey, encodingValue);
-        
-        final String exampleKey = "myExample";
-        final Example exampleValue = createConstructibleInstance(Example.class);
-        checkSameObject(mt, mt.addExample(exampleKey, exampleValue));
-        checkMapEntry(mt.getExamples(), exampleKey, exampleValue);
+        processConstructible(MediaType.class);
     }
     
     @Test
     public void schemaTest() {
-        final Schema s = processConstructible(Schema.class);
-        
-        final Schema allOf = createConstructibleInstance(Schema.class);
-        checkSameObject(s, s.addAllOf(allOf));
-        checkListEntry(s.getAllOf(), allOf);
-        
-        final Schema anyOf = createConstructibleInstance(Schema.class);
-        checkSameObject(s, s.addAnyOf(anyOf));
-        checkListEntry(s.getAnyOf(), anyOf);
-        
-        final String enumeration = new String("enumValue");
-        checkSameObject(s, s.addEnumeration(enumeration));
-        checkListEntry(s.getEnumeration(), enumeration);
-        
-        final Schema oneOf = createConstructibleInstance(Schema.class);
-        checkSameObject(s, s.addOneOf(oneOf));
-        checkListEntry(s.getOneOf(), oneOf);
-        
-        final String propertySchemaKey = "myPropertySchemaKey";
-        final Schema propertySchemaValue = createConstructibleInstance(Schema.class);
-        checkSameObject(s, s.addProperty(propertySchemaKey, propertySchemaValue));
-        checkMapEntry(s.getProperties(), propertySchemaKey, propertySchemaValue);
-        
-        final String required = new String("required");
-        checkSameObject(s, s.addRequired(required));
-        checkListEntry(s.getRequired(), required);
+        processConstructible(Schema.class);
     }
     
     @Test
@@ -425,25 +258,33 @@ public class ModelConstructionTest {
     @Test
     public void cookieParameterTest() {
         final CookieParameter cp = processConstructible(CookieParameter.class);
-        checkParameterCommon(cp, Parameter.In.COOKIE, "cookie");
+        // Check value of read-only 'in' property.
+        Assert.assertEquals("The value of the 'in' property is expected to be 'cookie'.",
+                Parameter.In.COOKIE, cp.getIn());
     }
-
+    
     @Test
     public void headerParameterTest() {
         final HeaderParameter hp = processConstructible(HeaderParameter.class);
-        checkParameterCommon(hp, Parameter.In.HEADER, "header");
+        // Check value of read-only 'in' property.
+        Assert.assertEquals("The value of the 'in' property is expected to be 'header'.",
+                Parameter.In.HEADER, hp.getIn());
     }
     
     @Test
     public void pathParameterTest() {
         final PathParameter pp = processConstructible(PathParameter.class);
-        checkParameterCommon(pp, Parameter.In.PATH, "path");
+        // Check value of read-only 'in' property.
+        Assert.assertEquals("The value of the 'in' property is expected to be 'path'.",
+                Parameter.In.PATH, pp.getIn());
     }
     
     @Test
     public void queryParameterTest() {
         final QueryParameter qp = processConstructible(QueryParameter.class);
-        checkParameterCommon(qp, Parameter.In.QUERY, "query");
+        // Check value of read-only 'in' property.
+        Assert.assertEquals("The value of the 'in' property is expected to be 'query'.",
+                Parameter.In.QUERY, qp.getIn());
     }
     
     @Test
@@ -453,34 +294,12 @@ public class ModelConstructionTest {
     
     @Test
     public void apiResponseTest() {
-        final APIResponse response = processConstructible(APIResponse.class);
-        
-        final String headerKey = "myHeaderKey";
-        final Header headerValue = createConstructibleInstance(Header.class);
-        checkSameObject(response, response.addHeader(headerKey, headerValue));
-        checkMapEntry(response.getHeaders(), headerKey, headerValue);
-        
-        final String linkKey = "myLinkKey";
-        final Link linkValue = createConstructibleInstance(Link.class);
-        checkSameObject(response, response.addLink(linkKey, linkValue));
-        checkMapEntry(response.getLinks(), linkKey, linkValue);
+        processConstructible(APIResponse.class);
     }
     
     @Test
     public void apiResponsesTest() {
-        final APIResponses responses = processConstructible(APIResponses.class);
-        
-        final String responseKey = "myResponse";
-        final APIResponse responseValue = createConstructibleInstance(APIResponse.class);
-        checkSameObject(responses, responses.addApiResponse(responseKey, responseValue));
-        checkMapEntry(responses, responseKey, responseValue);
-        
-        final String responseKey2 = "myResponse2";
-        final APIResponse responseValue2 = createConstructibleInstance(APIResponse.class);
-        Assert.assertNull("No previous mapping expected.", responses.put(responseKey2, responseValue2));
-        checkMapEntry(responses, responseKey2, responseValue2);
-        
-        Assert.assertEquals("The map is expected to contain two entries.", 2, responses.size());
+        processConstructible(APIResponses.class);
     }
     
     @Test
@@ -495,36 +314,12 @@ public class ModelConstructionTest {
     
     @Test
     public void scopesTest() {
-        final Scopes s = processConstructible(Scopes.class);
-        
-        final String scopeKey = "myScope";
-        final String scopeValue = new String("myDescription");
-        checkSameObject(s, s.addScope(scopeKey, scopeValue));
-        checkMapEntry(s, scopeKey, scopeValue);
-        
-        final String scopeKey2 = "myScope2";
-        final String scopeValue2 = new String("myDescription2");
-        Assert.assertNull("No previous mapping expected.", s.put(scopeKey2, scopeValue2));
-        checkMapEntry(s, scopeKey2, scopeValue2);
-        
-        Assert.assertEquals("The map is expected to contain two entries.", 2, s.size());
+        processConstructible(Scopes.class);
     }
     
     @Test
     public void securityRequirementTest() {
-        final SecurityRequirement sr = processConstructible(SecurityRequirement.class);
-        
-        final String schemeKey = "myResponse";
-        final List<String> schemeValue = new ArrayList<String>();
-        checkSameObject(sr, sr.addScheme(schemeKey, schemeValue));
-        checkMapEntry(sr, schemeKey, schemeValue);
-        
-        final String schemeKey2 = "myResponse2";
-        final List<String> schemeValue2 = new ArrayList<String>();
-        Assert.assertNull("No previous mapping expected.", sr.put(schemeKey2, schemeValue2));
-        checkMapEntry(sr, schemeKey2, schemeValue2);
-        
-        Assert.assertEquals("The map is expected to contain two entries.", 2, sr.size());
+        processConstructible(SecurityRequirement.class);
     }
     
     @Test
@@ -539,28 +334,12 @@ public class ModelConstructionTest {
     
     @Test
     public void serverVariableTest() {
-        final ServerVariable sv = processConstructible(ServerVariable.class);
-        
-        final String enumeration = new String("enumValue");
-        checkSameObject(sv, sv.addEnumeration(enumeration));
-        checkListEntry(sv.getEnumeration(), enumeration);
+        processConstructible(ServerVariable.class);
     }
     
     @Test
     public void serverVariablesTest() {
-        final ServerVariables svs = processConstructible(ServerVariables.class);
-        
-        final String varKey = "myServerVariable";
-        final ServerVariable varValue = createConstructibleInstance(ServerVariable.class);
-        checkSameObject(svs, svs.addServerVariable(varKey, varValue));
-        checkMapEntry(svs, varKey, varValue);
-        
-        final String varKey2 = "myServerVariable2";
-        final ServerVariable varValue2 = createConstructibleInstance(ServerVariable.class);
-        Assert.assertNull("No previous mapping expected.", svs.put(varKey2, varValue2));
-        checkMapEntry(svs, varKey2, varValue2);
-        
-        Assert.assertEquals("The map is expected to contain two entries.", 2, svs.size());
+        processConstructible(ServerVariables.class);
     }
     
     @Test
@@ -624,26 +403,11 @@ public class ModelConstructionTest {
         final String myRef1 = createReference(r, "myRef1");
         r.setRef(myRef1);
         Assert.assertEquals("The return value of getRef() is expected to be equal to the value that was set.", myRef1, r.getRef());
-        // Check that the short name ref value can be set using the setter method and that the getter method returns the expanded value.
-        if (!(r instanceof PathItem)) {
-            final String shortName = "myRef2";
-            final String myRef2 = createReference(r, shortName);
-            r.setRef(shortName);
-            Assert.assertEquals("The return value of getRef() is expected to be a fully expanded name.", myRef2, r.getRef());
-        }
         // Check that the ref value can be set using the builder method and that the getter method returns the same value.
-        final String myRef3 = createReference(r, "myRef3");
-        final Reference<?> self = r.ref(myRef3);
+        final String myRef2 = createReference(r, "myRef2");
+        final Reference<?> self = r.ref(myRef2);
         Assert.assertSame("The return value of ref() is expected to return the current instance.", r, self);
-        Assert.assertEquals("The return value of getRef() is expected to be equal to the value that was set.", myRef3, r.getRef());
-        // Check that the short name ref value can be set using the builder method and that the getter method returns the expanded value.
-        if (!(r instanceof PathItem)) {
-            final String shortName = "myRef4";
-            final String myRef4 = createReference(r, shortName);
-            final Reference<?> self2 = r.ref(shortName);
-            Assert.assertSame("The return value of ref() is expected to return the current instance.", r, self2);
-            Assert.assertEquals("The return value of getRef() is expected to be a fully expanded name.", myRef4, r.getRef());
-        }
+        Assert.assertEquals("The return value of getRef() is expected to be equal to the value that was set.", myRef2, r.getRef());
     }
     
     private void processConstructibleProperty(Constructible o, Property p, Class<?> enclosingInterface) {
@@ -843,31 +607,4 @@ public class ModelConstructionTest {
         });
         return properties;
     }
-    
-    private <T extends Parameter<T>> void checkParameterCommon(Parameter<T> p, Parameter.In expectedIn, String name) {
-        final String exampleKey = "myExample";
-        final Example exampleValue = createConstructibleInstance(Example.class);
-        checkSameObject(p, p.addExample(exampleKey, exampleValue));
-        checkMapEntry(p.getExamples(), exampleKey, exampleValue);
-        
-        // Check value of read-only 'in' property.
-        Assert.assertEquals("The value of the 'in' property is expected to be '" + name + "'.",
-                expectedIn, p.getIn());
-    }
-    
-    private <T> void checkMapEntry(Map<String,T> map, String key, T value) {
-        Assert.assertNotNull("The map must not be null.", map);
-        Assert.assertTrue("The map is expected to contain the key: " + key, map.containsKey(key));
-        Assert.assertSame("The value associated with the key: " + key + " is expected to be the same one that was added.",
-                value, map.get(key));
-    }
-    
-    private <T> void checkListEntry(List<T> list, T value) {
-        Assert.assertNotNull("The list must not be null.", list);
-        Assert.assertTrue("The list is expected to contain the value: " + value, list.stream().anyMatch((v) -> v == value));
-    }
-    
-    private <T> void checkSameObject(T expected, T actual) {
-        Assert.assertSame("Expecting same object.", expected, actual);
-    }
 }