Started documentation.

Author: ben-madley-mt

src/main/kotlin/uk/gov/justice/digital/hmpps/hmppsintegrationapi/controllers/v1/BalancesController.kt

@@ -1,5 +1,9 @@
 package uk.gov.justice.digital.hmpps.hmppsintegrationapi.controllers.v1
 
+import io.swagger.v3.oas.annotations.Operation
+import io.swagger.v3.oas.annotations.media.Content
+import io.swagger.v3.oas.annotations.media.Schema
+import io.swagger.v3.oas.annotations.responses.ApiResponse
 import org.springframework.beans.factory.annotation.Autowired
 import org.springframework.web.bind.annotation.GetMapping
 import org.springframework.web.bind.annotation.PathVariable
@@ -9,6 +13,7 @@ import uk.gov.justice.digital.hmpps.hmppsintegrationapi.exception.BadRequestExce
 import uk.gov.justice.digital.hmpps.hmppsintegrationapi.exception.EntityNotFoundException
 import uk.gov.justice.digital.hmpps.hmppsintegrationapi.exception.InternalServerErrorException
 import uk.gov.justice.digital.hmpps.hmppsintegrationapi.models.hmpps.Balances
+import uk.gov.justice.digital.hmpps.hmppsintegrationapi.models.hmpps.DataResponse
 import uk.gov.justice.digital.hmpps.hmppsintegrationapi.models.hmpps.Response
 import uk.gov.justice.digital.hmpps.hmppsintegrationapi.models.hmpps.UpstreamApiError
 import uk.gov.justice.digital.hmpps.hmppsintegrationapi.services.GetBalancesForPersonService
@@ -17,7 +22,21 @@ import uk.gov.justice.digital.hmpps.hmppsintegrationapi.services.GetBalancesForP
 @RequestMapping("/v1/prison/{prisonId}/prisoners/{hmppsId}/balances")
 class BalancesController(@Autowired val getBalancesForPersonService: GetBalancesForPersonService,) {
   @GetMapping()
-  fun getBalancesForPerson(@PathVariable hmppsId: String, @PathVariable prisonId: String): Response<Balances?> {
+  @Operation(
+    summary = "Returns a all accounts for a prisoner that they have at a prison.",
+    description = "<b>Applicable filters</b>: <ul><li>prisons</li></ul>",
+    responses = [
+      ApiResponse(responseCode = "200", useReturnTypeSchema = true, description = "Successfully found a prisoner's accounts."),
+      ApiResponse(
+        responseCode = "400",
+        description = "The HMPPS ID provided has an invalid format or the prisoner does hot have accounts at the specified prison.",
+        content = [Content(schema = Schema(ref = "#/components/schemas/BadRequest"))],
+      ),
+      ApiResponse(responseCode = "404", content = [Content(schema = Schema(ref = "#/components/schemas/PersonNotFound"))]),
+      ApiResponse(responseCode = "500", content = [Content(schema = Schema(ref = "#/components/schemas/InternalServerError"))]),
+    ],
+  )
+  fun getBalancesForPerson(@PathVariable hmppsId: String, @PathVariable prisonId: String): DataResponse<Balances?> {
     val response = getBalancesForPersonService.execute(prisonId, hmppsId)
 
     if (response.hasError(UpstreamApiError.Type.ENTITY_NOT_FOUND)) {
@@ -31,6 +50,6 @@ class BalancesController(@Autowired val getBalancesForPersonService: GetBalances
     if (response.hasError(UpstreamApiError.Type.INTERNAL_SERVER_ERROR)) {
       throw InternalServerErrorException("Error occurred while trying to get accounts for person with id: $hmppsId")
     }
-    return response
+    return DataResponse(response.data)
   }
 }