From c92e02222bfcc476723039f7ec004b7710b2eb15 Mon Sep 17 00:00:00 2001
From: Tamino Dauth <tamino@cdauth.eu>
Date: Tue, 20 Nov 2018 19:39:33 +0100
Subject: [PATCH] Add missing REST parameter annotations and improve paths #1

---
 README.md                                     |  4 +--
 .../rest/GuiStateMachineService.scala         | 28 ++++++++++++++-----
 2 files changed, 23 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index 5852e69..04d2fe3 100644
--- a/README.md
+++ b/README.md
@@ -33,7 +33,7 @@ For example, whenever a random action is executed with the help of monkey testin
 After running the genetic algorithm, the state machine is then used to create a test suite.
 
 ## Scala API for GUI State Machines
-The package [api](./src/main/scala/de/retest/guistatemachine/api/) contains all types and methods for getting and modifying the GUI state machine.
+The package [api](./src/main/scala/de/retest/guistatemachine/api) contains all types and methods for getting and modifying the GUI state machine.
 
 ## REST API
 At the moment there is only an initial version of a REST API which has to be mapped to the Scala API.
@@ -46,4 +46,4 @@ curl -H "Content-Type: application/json" -X POST http://localhost:8888/state-mac
 
 ### Swagger Support
 The Swagger support is based on [swagger-akka-http](https://github.com/swagger-akka-http/swagger-akka-http).
-The URL `http://localhost:8888/api-docs/swagger.json` should show create Swagger JSON output which can be rendered by Swagger UI.
\ No newline at end of file
+The URL `http://localhost:8888/api-docs/swagger.json` should produce Swagger JSON output which can be rendered by [Swagger UI](https://swagger.io/tools/swagger-ui/).
\ No newline at end of file
diff --git a/src/main/scala/de/retest/guistatemachine/rest/GuiStateMachineService.scala b/src/main/scala/de/retest/guistatemachine/rest/GuiStateMachineService.scala
index 4d985f4..797b5d4 100644
--- a/src/main/scala/de/retest/guistatemachine/rest/GuiStateMachineService.scala
+++ b/src/main/scala/de/retest/guistatemachine/rest/GuiStateMachineService.scala
@@ -5,15 +5,16 @@ import akka.http.scaladsl.model.{StatusCode, StatusCodes}
 import akka.http.scaladsl.server.{Directives, Route}
 import de.retest.guistatemachine.api.{GuiStateMachine, GuiStateMachineApi, Id, State}
 import de.retest.guistatemachine.rest.json.DefaultJsonFormats
-import io.swagger.annotations.{Api, ApiOperation, ApiResponse, ApiResponses}
+import io.swagger.annotations.{Api, ApiImplicitParam, ApiOperation, ApiResponse, ApiResponses}
 import javax.ws.rs.Path
 
-@Api(value = "/state-machine", description = "Gets a state machine")
-@Path("/state-machine")
+@Api(value = "state-machine")
+@Path("state-machine")
 class GuiStateMachineService(api: GuiStateMachineApi) extends Directives with DefaultJsonFormats {
 
   def getRoute(): Route = getStateMachine() ~ deleteStateMachine() ~ postStateMachine() ~ getState()
 
+  @Path("{id}")
   @ApiOperation(httpMethod = "GET", response = classOf[GuiStateMachine], value = "Returns a state machine based on the ID")
   @ApiResponses(Array(new ApiResponse(code = 404, message = "State machine not found")))
   def getStateMachine(): Route = get {
@@ -26,6 +27,7 @@ class GuiStateMachineService(api: GuiStateMachineApi) extends Directives with De
     }
   }
 
+  @Path("{id}")
   @ApiOperation(httpMethod = "DELETE", response = classOf[StatusCode], value = "Returns the status code")
   @ApiResponses(
     Array(
@@ -49,33 +51,45 @@ class GuiStateMachineService(api: GuiStateMachineApi) extends Directives with De
     }
   }
 
+  @Path("{id}/get-state")
   @ApiOperation(httpMethod = "POST", response = classOf[State], value = "Returns the existing or newly created state")
+  @ApiImplicitParam(name = "state-body",
+                    value = "The descriptors and the initial never explored actions of the state",
+                    required = true,
+                    dataType = "GetStateBody",
+                    paramType = "body")
   @ApiResponses(Array(new ApiResponse(code = 404, message = "State machine not found")))
   def getState(): Route = post {
     path("state-machine" / LongNumber / "get-state") { id =>
       val app = api.getStateMachine(Id(id))
       app match {
-        case Some(x) => {
+        case Some(x) =>
           entity(as[GetStateBody]) { body =>
             complete(x.getState(body.descriptors, body.neverExploredActions))
           }
-        }
         case None => complete(StatusCodes.NotFound)
       }
     }
   }
 
+  @Path("{id}/execute-state")
   @ApiOperation(httpMethod = "POST", response = classOf[State], value = "Returns the state which is reached by executing this action")
+  @ApiImplicitParam(
+    name = "execute-action-body",
+    value = "The source state, the action and the target state in form of its descriptors and initial never explored actions",
+    required = true,
+    dataType = "ExecuteActionBody",
+    paramType = "body"
+  )
   @ApiResponses(Array(new ApiResponse(code = 404, message = "State machine not found")))
   def executeAction(): Route = post {
     path("state-machine" / LongNumber / "execute-action") { id =>
       val app = api.getStateMachine(Id(id))
       app match {
-        case Some(x) => {
+        case Some(x) =>
           entity(as[ExecuteActionBody]) { body =>
             complete(x.executeAction(body.from, body.a, body.descriptors, body.neverExploredActions))
           }
-        }
         case None => complete(StatusCodes.NotFound)
       }
     }