PI-1572: Add endpoint documentation to EPF integration service (#2403)

projects/effective-proposal-framework-and-delius/src/main/kotlin/uk/gov/justice/digital/hmpps/epf/CaseDetailsController.kt

@@ -1,5 +1,7 @@
 package uk.gov.justice.digital.hmpps.epf
 
+import io.swagger.v3.oas.annotations.Operation
+import io.swagger.v3.oas.annotations.responses.ApiResponse
 import org.springframework.security.access.prepost.PreAuthorize
 import org.springframework.web.bind.annotation.GetMapping
 import org.springframework.web.bind.annotation.PathVariable
@@ -9,6 +11,24 @@ import org.springframework.web.bind.annotation.RestController
 class CaseDetailsController(private val caseDetailsService: CaseDetailsService) {
     @PreAuthorize("hasRole('EPF_CONTEXT')")
     @GetMapping(value = ["/case-details/{crn}/{eventNumber}"])
+    @Operation(
+        summary = "Probation case information for the Effective Proposals Framework service",
+        description = """<p>Accepts the probation identifier (CRN) and Delius Event number
+            and returns a data structure giving background information on the probation case
+            for use in the Effective Proposals Framework system. The information is used to
+            reduce the need for the EPF user to re-key information already held in Delius.</p>
+            <p>Requires `ROLE_EPF_CONTEXT`.</p>
+        """,
+        responses = [
+            ApiResponse(responseCode = "200", description = "OK"),
+            ApiResponse(
+                responseCode = "404",
+                description = """A case with the provided CRN does not exist in Delius.
+                    Note: this could be the result of a merge or a deletion.
+            """
+            )
+        ]
+    )
     fun handle(
         @PathVariable("crn") crn: String,
         @PathVariable("eventNumber") eventNumber: Int