Add basic SwaggerDoc

src/main/kotlin/no/nb/mlt/wls/order/controller/OrderController.kt

@@ -53,8 +53,8 @@ class OrderController(val orderService: OrderService) {
         ),
         ApiResponse(
             responseCode = "400",
-            description = """Order payload is invalid and was not created.
-                An empty error message means the order already exists with the current ID.
+            description = """Order payload is invalid and was not updated.
+                This error is produced if the order specified does not exist.
                 Otherwise, the error message contains information about the invalid fields.""",
             content = [Content(schema = Schema())]
         ),
@@ -74,6 +74,55 @@ class OrderController(val orderService: OrderService) {
         @RequestBody payload: ApiOrderPayload
     ): ResponseEntity<ApiOrderPayload> = orderService.createOrder(payload)
 
+    @Operation(
+        summary = "Updates an existing order in the storage system",
+        description = """Updates a specified order to the various storage systems via Hermes WLS.
+            If the storage systems support it, updates are also sent to them for processing the respective product(s).
+        """
+    )
+    @ApiResponses(
+        ApiResponse(
+            responseCode = "200",
+            description = """Order with given 'hostName' and 'hostOrderId' already exists in the system.
+                No new order was created, neither was the old order updated.
+                Existing order information is returned for inspection.
+                In rare cases the response body may be empty, that can happen if Hermes WLS does not
+                have the information about the order stored in its database and is unable to retrieve
+                the existing order information from the storage system.""",
+            content = [
+                Content(
+                    mediaType = "application/json",
+                    schema = Schema(implementation = ApiOrderPayload::class)
+                )
+            ]
+        ),
+        ApiResponse(
+            responseCode = "200",
+            description = "The order was updated with the new products, and sent to appropriate systems",
+            content = [
+                Content(
+                    mediaType = "application/json",
+                    schema = Schema(implementation = ApiOrderPayload::class)
+                )
+            ]
+        ),
+        ApiResponse(
+            responseCode = "400",
+            description = """Order payload is invalid and the order was not updated.
+                The error message contains information about the invalid fields.""",
+            content = [Content(schema = Schema())]
+        ),
+        ApiResponse(
+            responseCode = "401",
+            description = "Client sending the request is not authorized order products.",
+            content = [Content(schema = Schema())]
+        ),
+        ApiResponse(
+            responseCode = "403",
+            description = "A valid 'Authorization' header is missing from the request.",
+            content = [Content(schema = Schema())]
+        )
+    )
     @PutMapping("/order")
     suspend fun updateOrder(
         @RequestBody payload: ApiOrderPayload