add docs info to controller; add endpoint to private-prisons role

Author: emmalanigan

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

@@ -1,7 +1,12 @@
 package uk.gov.justice.digital.hmpps.hmppsintegrationapi.controllers.v1.person
 
+import io.swagger.v3.oas.annotations.Operation
 import io.swagger.v3.oas.annotations.Parameter
+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 io.swagger.v3.oas.annotations.tags.Tag
+import jakarta.validation.ValidationException
 import org.springframework.beans.factory.annotation.Autowired
 import org.springframework.web.bind.annotation.GetMapping
 import org.springframework.web.bind.annotation.PathVariable
@@ -23,6 +28,20 @@ class CellLocationController(
   @Autowired val auditService: AuditService,
   @Autowired val getCellLocationForPersonService: GetCellLocationForPersonService,
 ) {
+  @Operation(
+    summary = "Returns the cell location of a person.",
+    description = "<b>Applicable filters</b>: <ul><li>prisons</li></ul>",
+    responses = [
+      ApiResponse(responseCode = "200", useReturnTypeSchema = true, description = "Successfully found a persons cell location."),
+      ApiResponse(
+        responseCode = "400",
+        description = "The HMPPS ID provided has an invalid format.",
+        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"))]),
+    ],
+  )
   @GetMapping("{hmppsId}/cell-location")
   fun getPersonCellLocation(
     @Parameter(description = "The HMPPS ID of the person") @PathVariable hmppsId: String,
@@ -33,6 +52,9 @@ class CellLocationController(
     if (response.hasError(UpstreamApiError.Type.ENTITY_NOT_FOUND)) {
       throw EntityNotFoundException("Could not find cell location for id: $hmppsId")
     }
+    if (response.hasError(UpstreamApiError.Type.BAD_REQUEST)) {
+      throw ValidationException("Invalid HMPPS ID: $hmppsId")
+    }
 
     auditService.createEvent("GET_PERSON_CELL_LOCATION", mapOf("hmppsId" to hmppsId))
 

src/main/resources/globals.yml

@@ -12,6 +12,7 @@ globals:
         - "/v1/persons/.*/visit-orders"
         - "/v1/persons/.*/visit/future"
         - "/v1/persons/.*/alerts"
+        - "/v1/persons/.*/cell-location"
         - "/v1/prison/prisoners"
         - "/v1/prison/prisoners/[^/]*$"
         - "/v1/prison/.*/prisoners/[^/]*/balances$"

src/test/kotlin/uk/gov/justice/digital/hmpps/hmppsintegrationapi/controllers/v1/person/CellLocationControllerTest.kt

@@ -118,6 +118,25 @@ internal class CellLocationControllerTest(
           result.response.status.shouldBe(HttpStatus.NOT_FOUND.value())
         }
 
+        it("returns a 400 BAD Request status code when an invalid hmpps id is found in the upstream API") {
+          whenever(getCellLocationForPersonService.execute(hmppsId, filters)).thenReturn(
+            Response(
+              data = null,
+              errors =
+                listOf(
+                  UpstreamApiError(
+                    causedBy = UpstreamApi.NOMIS,
+                    type = UpstreamApiError.Type.BAD_REQUEST,
+                  ),
+                ),
+            ),
+          )
+
+          val result = mockMvc.performAuthorised(path)
+
+          result.response.status.shouldBe(HttpStatus.BAD_REQUEST.value())
+        }
+
         it("fails with the appropriate error when an upstream service is down") {
           whenever(getCellLocationForPersonService.execute(hmppsId, filters)).doThrow(
             WebClientResponseException(500, "MockError", null, null, null, null),

src/test/kotlin/uk/gov/justice/digital/hmpps/hmppsintegrationapi/integration/person/PersonIntegrationTest.kt

@@ -1,8 +1,6 @@
 package uk.gov.justice.digital.hmpps.hmppsintegrationapi.integration.person
 
 import org.junit.jupiter.api.Test
-import org.junit.jupiter.params.ParameterizedTest
-import org.junit.jupiter.params.provider.ValueSource
 import org.springframework.test.web.servlet.result.MockMvcResultMatchers.content
 import org.springframework.test.web.servlet.result.MockMvcResultMatchers.status
 import uk.gov.justice.digital.hmpps.hmppsintegrationapi.integration.IntegrationTestBase
@@ -46,10 +44,10 @@ class PersonIntegrationTest : IntegrationTestBase() {
       )
   }
 
-  @ParameterizedTest
-  @ValueSource(strings = ["2004%2F13116M", "G2996UX"])
-  fun `returns person cell location if in prison`(hmppsId: String) {
-    callApi("$basePath/$hmppsId/cell-location")
+  // Cell Location tests
+  @Test
+  fun `returns person cell location if in prison`() {
+    callApi("$basePath/$nomsId/cell-location")
       .andExpect(status().isOk)
       .andExpect(
         content().json(
@@ -60,6 +58,25 @@ class PersonIntegrationTest : IntegrationTestBase() {
       )
   }
 
+  @Test
+  fun `cell location return a 404 for person in wrong prison`() {
+    callApiWithCN("$basePath/$nomsId/cell-location", limitedPrisonsCn)
+      .andExpect(status().isNotFound)
+  }
+
+  @Test
+  fun `cell location return a 404 when no prisons in filter`() {
+    callApiWithCN("$basePath/$nomsId/cell-location", noPrisonsCn)
+      .andExpect(status().isNotFound)
+  }
+
+  @Test
+  fun `cell location return a 400 when invalid noms passed in`() {
+    callApi("$basePath/$invalidNomsId/cell-location")
+      .andExpect(status().isBadRequest)
+  }
+
+  // Prisoner Contacts
   @Test
   fun `returns a prisoners contacts`() {
     val params = "?page=1&size=10"