Merge pull request #353 from AbsaOSS/doc-improvement

Doc improvement

consumer-rest-core/src/main/scala/za/co/absa/spline/consumer/rest/controller/ExecutionEventController.scala

@@ -17,30 +17,42 @@ package za.co.absa.spline.consumer.rest.controller
 
 import java.util.Date
 
-import io.swagger.annotations.ApiOperation
+import io.swagger.annotations.{ApiOperation, ApiParam}
 import org.springframework.beans.factory.annotation.Autowired
 import org.springframework.web.bind.annotation._
-import za.co.absa.spline.consumer.service.model.{ExecutionEvent, PageRequest, Pageable, SortRequest}
+import za.co.absa.spline.consumer.service.model._
 import za.co.absa.spline.consumer.service.repo.ExecutionEventRepository
 
 import scala.concurrent.Future
 
-@RestController
+@RestController("execution-event")
 class ExecutionEventController @Autowired()(val repo: ExecutionEventRepository) {
 
   import scala.concurrent.ExecutionContext.Implicits._
 
   @GetMapping(Array("/executionEvent"))
-  @ApiOperation("Returns a list of execution event info containing the time of the execution, the application Id/Name and the appendMode")
+  @ApiOperation(
+    value = "GET /executionEvent",
+    notes ="Returns a Pageable list of execution events within the time range given in parameters",
+    response = classOf[PageableExecutionEvent]
+  )
   def executionEvent
   (
-    @RequestParam(value = "timestampStart" , required = false, defaultValue = "0") timestampStart: Long,
+    @ApiParam(value = "Beginning of the timestamp range used for querying. If timestampStart equals 0, the service will return the first 100 execution events in database")
+    @RequestParam(value = "timestampStart", required = false, defaultValue = "0") timestampStart: Long,
+    @ApiParam(value = "End of the timestamp range used for querying")
     @RequestParam(value = "timestampEnd", required = false, defaultValue = "0") timestampEnd: Long,
+    @ApiParam(value = "Timestamp of the request, if asAtTime equals 0, the current timestamp will be applied")
     @RequestParam(value = "asAtTime", required = false, defaultValue = "0") asAtTime: Long,
+    @ApiParam(value = "Number of the page")
     @RequestParam(value = "offset", required = false, defaultValue = "0") offset: Int,
+    @ApiParam(value = "Size of the page")
     @RequestParam(value = "size", required = false, defaultValue = "10") size: Int,
+    @ApiParam(value = "Name of the attribute to sort on")
     @RequestParam(value = "sortName", required = false, defaultValue = "timestamp") sortName: String,
+    @ApiParam(value = "Sort Direction", example = "DESC")
     @RequestParam(value = "sortDirection", required = false, defaultValue = "ASC") sortDirection: String,
+    @ApiParam(value = "Text to filter the results")
     @RequestParam(value = "searchTerm", required = false) searchTerm: String
   ): Future[Pageable[ExecutionEvent]] = {
 

consumer-rest-core/src/main/scala/za/co/absa/spline/consumer/rest/controller/ExecutionPlanController.scala

@@ -16,7 +16,7 @@
 
 package za.co.absa.spline.consumer.rest.controller
 
-import io.swagger.annotations.ApiOperation
+import io.swagger.annotations.{ApiOperation, ApiParam}
 import org.springframework.beans.factory.annotation.Autowired
 import org.springframework.web.bind.annotation._
 import za.co.absa.spline.consumer.service.model.{DataSourceInfo, ExecutedLogicalPlan, ExecutionInfo}
@@ -32,14 +32,27 @@ class ExecutionPlanController @Autowired()(
   import scala.concurrent.ExecutionContext.Implicits._
 
   @GetMapping(Array("/{execId}/lineage"))
-  @ApiOperation("Returns a logical plan (aka partial lineage) of a given execution")
-  def lineage(@PathVariable("execId") execId: ExecutionInfo.Id): Future[ExecutedLogicalPlan] = {
+  @ApiOperation(
+    value="GET /execution/{execId}/lineage",
+    notes="Returns a logical plan (aka partial lineage) of a given execution)")
+  def lineage
+  (
+    @ApiParam(value = "Id of the execution to retrieve")
+    @PathVariable("execId") execId: ExecutionInfo.Id
+   ): Future[ExecutedLogicalPlan] = {
     repo.findById(execId)
   }
 
   @GetMapping(Array("/{execId}/info"))
-  @ApiOperation("Return information related the an Execution Plan")
-  def info(@PathVariable("execId") execId: ExecutionInfo.Id): Future[Array[DataSourceInfo]] = {
+  @ApiOperation(
+    value="GET /execution/{execId}/info",
+    notes="Return input datasource information related the an Execution Plan"
+  )
+  def info
+  (
+    @ApiParam(value = "Id of the execution to retrieve")
+    @PathVariable("execId") execId: ExecutionInfo.Id
+  ): Future[Array[DataSourceInfo]] = {
     repo.findInputDataSourceInfoById(execId)
   }
 }

consumer-rest-core/src/main/scala/za/co/absa/spline/consumer/rest/controller/LineageController.scala

@@ -16,7 +16,7 @@
 
 package za.co.absa.spline.consumer.rest.controller
 
-import io.swagger.annotations.ApiOperation
+import io.swagger.annotations.{ApiOperation, ApiParam}
 import org.springframework.beans.factory.annotation.Autowired
 import org.springframework.web.bind.annotation._
 import za.co.absa.spline.consumer.service.model.LineageOverview
@@ -30,8 +30,17 @@ class LineageController @Autowired()(val repo: LineageRepository) {
   import scala.concurrent.ExecutionContext.Implicits._
 
   @GetMapping(Array("/lineage"))
-  @ApiOperation("Returns a lineage overview of a given dataSource Id and an application Id and")
-  def lineage(@RequestParam("path") path: String, @RequestParam("applicationId") applicationId: String): Future[LineageOverview] = {
+  @ApiOperation(
+    value = "GET /lineage",
+    notes = "Returns a lineage overview of a given dataSource uri and an application Id and"
+  )
+  def lineage
+  (
+    @ApiParam(value="Output DataSource uri")
+    @RequestParam("path") path: String,
+    @ApiParam(value="Id of the application")
+    @RequestParam("applicationId") applicationId: String
+  ): Future[LineageOverview] = {
     repo.findByApplicationIdAndPath(path, applicationId)
   }
 

consumer-rest-core/src/main/scala/za/co/absa/spline/consumer/rest/controller/OperationDetailsController.scala

@@ -16,7 +16,7 @@
 
 package za.co.absa.spline.consumer.rest.controller
 
-import io.swagger.annotations.ApiOperation
+import io.swagger.annotations.{ApiOperation, ApiParam}
 import org.springframework.beans.factory.annotation.Autowired
 import org.springframework.web.bind.annotation._
 import za.co.absa.spline.consumer.service.model._
@@ -28,14 +28,22 @@ import scala.concurrent.Future
 
 @RestController
 @RequestMapping(Array("/operation"))
-class OperationDetailsController @Autowired()(
+class OperationDetailsController @Autowired()
+(
   val repo: OperationRepository) {
 
   import scala.concurrent.ExecutionContext.Implicits._
 
   @GetMapping(Array("/{operationId}"))
-  @ApiOperation("Returns details of an operation node")
-  def operation(@PathVariable("operationId") operationId: Operation.Id): Future[OperationDetails] = {
+  @ApiOperation(
+    value = "GET /operation/{operationId}",
+    notes = "Returns details of an operation node"
+  )
+  def operation
+  (
+    @ApiParam(value = "Id of the operation node to retrieve")
+    @PathVariable("operationId") operationId: Operation.Id
+  ): Future[OperationDetails] = {
     val result: Future[OperationDetails] = repo.findById(operationId)
 
     result.map(res => {
@@ -46,8 +54,17 @@ class OperationDetailsController @Autowired()(
   }
 
   @GetMapping(Array("/info"))
-  @ApiOperation("Returns details of an operation node from a sourceId")
-  def operationFromSourceAndApplicationId(@RequestParam("source") source: String, @RequestParam("applicationId") applicationId: String): Future[OperationDetails] = {
+  @ApiOperation(
+    value = "GET /operation/info",
+    notes = "Returns details of an operation node from a DataSource uri and an applicationId"
+  )
+  def operationFromSourceAndApplicationId
+  (
+    @ApiParam(value = "DataSource uri related to the operation (Output DataSource uri for a Write Operation or one of the Input DataSources uri if it is a Read Operation)")
+    @RequestParam("source") source: String,
+    @ApiParam(value = "Id of the application that triggered the operation")
+    @RequestParam("applicationId") applicationId: String
+  ): Future[OperationDetails] = {
     val result: Future[OperationDetails] = repo.findBySourceAndApplicationId(source, applicationId)
 
     result.map(res => {

consumer-services/pom.xml

@@ -30,6 +30,10 @@
     <artifactId>consumer-services</artifactId>
 
     <dependencies>
+        <dependency>
+            <groupId>io.swagger</groupId>
+            <artifactId>swagger-annotations</artifactId>
+        </dependency>
         <dependency>
             <groupId>za.co.absa.spline</groupId>
             <artifactId>persistence</artifactId>

consumer-services/src/main/scala/za/co/absa/spline/consumer/service/model/DataSourceInfo.scala

@@ -15,8 +15,14 @@
  */
 package za.co.absa.spline.consumer.service.model
 
-case class DataSourceInfo(
+import io.swagger.annotations.{ApiModel, ApiModelProperty}
+
+@ApiModel(description = "Information about the DataSource")
+case class DataSourceInfo
+(
+  @ApiModelProperty(value = "Type of the dataSource", example = "csv / parquet")
   sourceType: String,
+  @ApiModelProperty(value = "Uri of the dataSource")
   source: String
 ) {
   def this() = this("", "")

consumer-services/src/main/scala/za/co/absa/spline/consumer/service/model/ExecutedLogicalPlan.scala

@@ -16,9 +16,15 @@
 
 package za.co.absa.spline.consumer.service.model
 
+import io.swagger.annotations.{ApiModel, ApiModelProperty}
+
+
+@ApiModel(description = "Execution And Lineage Graph")
 case class ExecutedLogicalPlan
 (
+  @ApiModelProperty(value = "Information related to the execution")
   execution: ExecutionInfo,
+  @ApiModelProperty(value = "Lineage of the execution")
   plan: LogicalPlan
 ) {
   def this() = this(null, null)

consumer-services/src/main/scala/za/co/absa/spline/consumer/service/model/ExecutionEvent.scala

@@ -15,15 +15,35 @@
  */
 package za.co.absa.spline.consumer.service.model
 
+import io.swagger.annotations.ApiModelProperty
+
 case class ExecutionEvent
 (
-  frameworkName : String,
+  @ApiModelProperty(value = "Name of the framework that triggered this execution event")
+  frameworkName: String,
+  @ApiModelProperty(value = "Name of the application/job")
   applicationName: String,
-  applicationId : String,
-  timestamp : Long,
-  datasource : String,
-  datasourceType : String,
-  append : Boolean
-){
-  def this() = this("", "", "", 0, "", "", false)
+  @ApiModelProperty(value = "Id of the application/job")
+  applicationId: String,
+  @ApiModelProperty(value = "When the execution was triggered")
+  timestamp: Long,
+  @ApiModelProperty(value = "Output file uri")
+  datasource: String,
+  @ApiModelProperty(value = "Type of the output file")
+  datasourceType: String,
+  @ApiModelProperty(value = "Write mode - (true=Append; false=Override)")
+  append: Boolean
+) {
+  def this() = this(null, null, null, 0, null, null, false)
 }
+
+case class PageableExecutionEvent() extends Pageable[ExecutionEvent] {
+  @ApiModelProperty(value = "Array of Execution events")
+  override val elements: Array[ExecutionEvent] = Array.empty
+  @ApiModelProperty(value = "Total number of executionEvents retrieved")
+  override val totalCount: Long = 0
+  @ApiModelProperty(value = "Page index")
+  override val offset: Int = 0
+  @ApiModelProperty(value = "Page size")
+  override val size: Int = 0
+}

consumer-services/src/main/scala/za/co/absa/spline/consumer/service/model/ExecutionInfo.scala

@@ -19,10 +19,14 @@ package za.co.absa.spline.consumer.service.model
 import java.util.UUID
 
 import ExecutionInfo.Id
+import io.swagger.annotations.{ApiModel, ApiModelProperty}
 
+@ApiModel(description="Information of the retrieved execution")
 case class ExecutionInfo
 (
+  @ApiModelProperty(value = "Execution Id")
   _id: Id,
+  @ApiModelProperty(value = "Information Map related to the execution containing for instance the list of attributes, the data types and extra info of the agent and the framework used")
   extra: Map[String, Any]
 ) {
   def this() = this(null, null)

consumer-services/src/main/scala/za/co/absa/spline/consumer/service/model/Lineage.scala

@@ -16,8 +16,14 @@
 
 package za.co.absa.spline.consumer.service.model
 
-case class Lineage(
+import io.swagger.annotations.{ApiModel, ApiModelProperty}
+
+@ApiModel(description = "Lineage")
+case class Lineage
+(
+  @ApiModelProperty(value = "Array of Lineage Overview nodes representing an Execution or a DataSource")
   nodes: Array[LineageOverviewNode],
+  @ApiModelProperty(value = "Link between the Executions and the DataSources")
   edges: Array[Transition]
 ) extends Graph {
   def this() = this(null, null)

consumer-services/src/main/scala/za/co/absa/spline/consumer/service/model/LineageOverview.scala

@@ -15,9 +15,15 @@
  */
 package za.co.absa.spline.consumer.service.model
 
-case class LineageOverview(
-  lineageInfo : Map[String, Any],
-  lineage : Lineage
-  ) {
+import io.swagger.annotations.{ApiModel, ApiModelProperty}
+
+@ApiModel(description = "Lineage Overview")
+case class LineageOverview
+(
+  @ApiModelProperty(value = "Lineage information Map containing for instance the application Id and the Timestamp")
+  lineageInfo: Map[String, Any],
+  @ApiModelProperty(value = "Related Lineage")
+  lineage: Lineage
+) {
   def this() = this(null, null)
 }

consumer-services/src/main/scala/za/co/absa/spline/consumer/service/model/LogicalPlan.scala

@@ -16,7 +16,16 @@
 
 package za.co.absa.spline.consumer.service.model
 
-case class LogicalPlan(nodes: Array[Operation], edges: Array[Transition]) extends Graph {
+import io.swagger.annotations.{ApiModel, ApiModelProperty}
+
+@ApiModel(description = "Lineage Graph")
+case class LogicalPlan
+(
+  @ApiModelProperty(value = "List of graph nodes representing the different operations of the lineage")
+  nodes: Array[Operation],
+  @ApiModelProperty(value = "List of graph edges showing the triggered operations order")
+  edges: Array[Transition]
+) extends Graph {
   def this() = this(null, null)
 
   override type Node = Operation

consumer-services/src/main/scala/za/co/absa/spline/consumer/service/model/Operation.scala

@@ -16,15 +16,22 @@
 
 package za.co.absa.spline.consumer.service.model
 
+import io.swagger.annotations.{ApiModel, ApiModelProperty}
 import za.co.absa.spline.consumer.service.model.ExecutedLogicalPlan.OperationID
 
-case class Operation(
-                      _id: OperationID,
-                      _type: String,
-                      name: String,
-                      readsFrom: Seq[DataSourceInfo],
-                      writesTo: DataSourceInfo
-                    ) extends Graph.Node {
+@ApiModel(description = "Operation")
+case class Operation
+(
+  @ApiModelProperty(value = "Operation Id")
+  _id: OperationID,
+  @ApiModelProperty(value = "Type of the operation", example = "Read / Transformation / Write")
+  _type: String,
+  @ApiModelProperty(value = "Name of the operation")
+  name: String,
+  @ApiModelProperty(value = "List of the operation input dataSources")
+  readsFrom: Seq[DataSourceInfo],
+  writesTo: DataSourceInfo
+) extends Graph.Node {
   override type Id = OperationID
 
   def this() = this(null, null, null, null, null)

consumer-services/src/main/scala/za/co/absa/spline/consumer/service/model/OperationDetails.scala

@@ -17,14 +17,20 @@
 package za.co.absa.spline.consumer.service.model
 
 
+import io.swagger.annotations.{ApiModel, ApiModelProperty}
 import za.co.absa.spline.persistence.{model => persistence}
 
+@ApiModel(description = "Information Details of an Operation containing the input and output schemas with the description of the dataTypes")
 case class OperationDetails
 (
   operation: Operation,
+  @ApiModelProperty(value = "Array of the used DataTypes in the schemas")
   dataTypes: Array[persistence.DataType],
+  @ApiModelProperty(value = "Array of all the schemas")
   schemas: Array[Array[persistence.Attribute]],
+  @ApiModelProperty(value = "Array of indexes of the schemas Array. The schemas at these indexes represent the input schemas")
   inputs: Array[Integer],
+  @ApiModelProperty(value = "Index of the schemas Array. The schema at this index represents the output schemas")
   output: Integer
 
 ) {

consumer-services/src/main/scala/za/co/absa/spline/consumer/service/model/Transition.scala

@@ -17,8 +17,16 @@
 package za.co.absa.spline.consumer.service.model
 
 import ExecutedLogicalPlan.OperationID
+import io.swagger.annotations.{ApiModel, ApiModelProperty}
 
-case class Transition(source: OperationID, target: OperationID) extends Graph.Edge {
+@ApiModel(description="Link between operations")
+case class Transition
+(
+  @ApiModelProperty(value = "Source Operation")
+  source: OperationID,
+  @ApiModelProperty(value = "Target Operation")
+  target: OperationID
+) extends Graph.Edge {
   def this() = this(null, null)
 
   override type JointId = OperationID