PI-2374 OpenAPI - remove mtls security option + add return types (#468)

Author: marcus-bcl

src/main/kotlin/uk/gov/justice/digital/hmpps/hmppsintegrationapi/config/OpenAPIConfig.kt

@@ -33,19 +33,15 @@ import org.springframework.context.annotation.Configuration
     Server(url = "https://hmpps-integration-api-prod.apps.live.cloud-platform.service.justice.gov.uk", description = "Production"),
   ],
   security = [
-    SecurityRequirement(name = "mutual-tls"),
-    SecurityRequirement(name = "api-key"),
+    SecurityRequirement(name = "dn"),
   ],
 )
 @SecurityScheme(
-  name = "mutual-tls",
-  type = SecuritySchemeType.MUTUALTLS,
-)
-@SecurityScheme(
-  name = "api-key",
+  name = "dn",
   type = SecuritySchemeType.APIKEY,
   `in` = SecuritySchemeIn.HEADER,
-  paramName = "x-api-key",
+  paramName = "subject-distinguished-name",
+  description = "Example: O=test,CN=automated-test-client",
 )
 @Configuration
 class OpenAPIConfig {
@@ -56,20 +52,33 @@ class OpenAPIConfig {
         openApi.components
           .addSchemas(
             "BadRequest",
-            Schema<ErrorResponse>()
-              .example(ErrorResponse(400, userMessage = "Validation failure: No query parameters specified.", developerMessage = "No query parameters specified.")),
+            Schema<ErrorResponse>().properties(
+              mapOf(
+                "status" to Schema<Int>().type("number").example(400),
+                "userMessage" to Schema<String>().type("string").example("Validation failure: No query parameters specified."),
+                "developerMessage" to Schema<String>().type("string").example("No query parameters specified."),
+              ),
+            ),
           )
           .addSchemas(
             "PersonNotFound",
-            Schema<ErrorResponse>()
-              .description("Failed to find a person with the provided HMPPS ID.")
-              .example(ErrorResponse(404, userMessage = "404 Not found error: Could not find person with HMPPS id: 2003/0011991D.", developerMessage = "Could not find person with HMPPS id: 2003/0011991D.")),
+            Schema<ErrorResponse>().description("Failed to find a person with the provided HMPPS ID.").properties(
+              mapOf(
+                "status" to Schema<Int>().type("number").example(404),
+                "userMessage" to Schema<String>().type("string").example("404 Not found error: Could not find person with HMPPS id: 2003/0011991D."),
+                "developerMessage" to Schema<String>().type("string").example("Could not find person with HMPPS id: 2003/0011991D."),
+              ),
+            ),
           )
           .addSchemas(
             "InternalServerError",
-            Schema<ErrorResponse>()
-              .description("An upstream service was not responding, so we cannot verify the accuracy of any data we did get.")
-              .example(ErrorResponse(500, userMessage = "Internal Server Error", developerMessage = "Unable to complete request as an upstream service is not responding.")),
+            Schema<ErrorResponse>().description("An upstream service was not responding, so we cannot verify the accuracy of any data we did get.").properties(
+              mapOf(
+                "status" to Schema<Int>().type("number").example(500),
+                "userMessage" to Schema<String>().type("string").example("Internal Server Error"),
+                "developerMessage" to Schema<String>().type("string").example("Unable to complete request as an upstream service is not responding."),
+              ),
+            ),
           )
       }
     }

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

@@ -34,7 +34,7 @@ class EPFPersonDetailController(
       reduce the need for the EPF user to re-key information already held in Delius.</p>
     """,
     responses = [
-      ApiResponse(responseCode = "200"),
+      ApiResponse(responseCode = "200", useReturnTypeSchema = true),
       ApiResponse(responseCode = "404", content = [Content(schema = Schema(ref = "#/components/schemas/PersonNotFound"))]),
       ApiResponse(responseCode = "500", content = [Content(schema = Schema(ref = "#/components/schemas/InternalServerError"))]),
     ],

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

@@ -27,7 +27,7 @@ class ImageController(
   @Operation(
     summary = "Returns an image in bytes as a JPEG.",
     responses = [
-      ApiResponse(responseCode = "200", description = "Successfully found an image with the provided ID."),
+      ApiResponse(responseCode = "200", useReturnTypeSchema = true, description = "Successfully found an image with the provided ID."),
       ApiResponse(responseCode = "404", description = "Failed to find an image with the provided ID.", content = [Content(schema = Schema(ref = "#/components/schemas/PersonNotFound"))]),
       ApiResponse(responseCode = "500", content = [Content(schema = Schema(ref = "#/components/schemas/InternalServerError"))]),
     ],

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

@@ -34,7 +34,7 @@ class RiskManagementController(
   @Operation(
     summary = "Returns a list of Risk Management Plans created for the person with the provided HMPPS ID.",
     responses = [
-      ApiResponse(responseCode = "200", description = "Successfully found risk management plans for a person with the provided HMPPS ID."),
+      ApiResponse(responseCode = "200", useReturnTypeSchema = true, description = "Successfully found risk management plans for a person with the provided HMPPS ID."),
       ApiResponse(responseCode = "404", content = [Content(schema = Schema(ref = "#/components/schemas/PersonNotFound"))]),
       ApiResponse(responseCode = "500", content = [Content(schema = Schema(ref = "#/components/schemas/InternalServerError"))]),
     ],

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

@@ -31,7 +31,7 @@ class AddressController(
   @Operation(
     summary = "Returns addresses associated with a person, ordered by startDate.",
     responses = [
-      ApiResponse(responseCode = "200", description = "Successfully found a person with the provided HMPPS ID."),
+      ApiResponse(responseCode = "200", useReturnTypeSchema = true, description = "Successfully found a person with the provided HMPPS ID."),
       ApiResponse(responseCode = "404", content = [Content(schema = Schema(ref = "#/components/schemas/PersonNotFound"))]),
       ApiResponse(responseCode = "500", content = [Content(schema = Schema(ref = "#/components/schemas/InternalServerError"))]),
     ],

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

@@ -32,7 +32,7 @@ class AdjudicationsController(
   @Operation(
     summary = "Returns adjudications associated with a person, sorted by dateTimeOfIncident (newest first).",
     responses = [
-      ApiResponse(responseCode = "200", description = "OK"),
+      ApiResponse(responseCode = "200", useReturnTypeSchema = true, description = "OK"),
       ApiResponse(responseCode = "404", description = "Failed to find adjudications for the person with the provided hmppsId.", content = [Content(schema = Schema(ref = "#/components/schemas/PersonNotFound"))]),
       ApiResponse(responseCode = "500", content = [Content(schema = Schema(ref = "#/components/schemas/InternalServerError"))]),
     ],

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

@@ -33,7 +33,7 @@ class AlertsController(
   @Operation(
     summary = "Returns alerts associated with a person, sorted by dateCreated (newest first).",
     responses = [
-      ApiResponse(responseCode = "200", description = "Successfully found alerts for a person with the provided HMPPS ID."),
+      ApiResponse(responseCode = "200", useReturnTypeSchema = true, description = "Successfully found alerts for a person with the provided HMPPS ID."),
       ApiResponse(responseCode = "404", content = [Content(schema = Schema(ref = "#/components/schemas/PersonNotFound"))]),
       ApiResponse(responseCode = "500", content = [Content(schema = Schema(ref = "#/components/schemas/InternalServerError"))]),
     ],
@@ -57,7 +57,7 @@ class AlertsController(
   @Operation(
     summary = "Returns alerts associated with a person, sorted by dateCreated (newest first).",
     responses = [
-      ApiResponse(responseCode = "200", description = "Successfully found alerts for a person with the provided HMPPS ID."),
+      ApiResponse(responseCode = "200", useReturnTypeSchema = true, description = "Successfully found alerts for a person with the provided HMPPS ID."),
       ApiResponse(responseCode = "404", content = [Content(schema = Schema(ref = "#/components/schemas/PersonNotFound"))]),
       ApiResponse(responseCode = "500", content = [Content(schema = Schema(ref = "#/components/schemas/InternalServerError"))]),
     ],

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

@@ -36,7 +36,7 @@ class CaseNotesController(
   @Operation(
     summary = "Returns case notes associated with a person.",
     responses = [
-      ApiResponse(responseCode = "200", description = "Successfully found case notes for a person with the provided HMPPS ID."),
+      ApiResponse(responseCode = "200", useReturnTypeSchema = true, description = "Successfully found case notes for a person with the provided HMPPS ID."),
       ApiResponse(responseCode = "404", content = [Content(schema = Schema(ref = "#/components/schemas/PersonNotFound"))]),
       ApiResponse(responseCode = "500", content = [Content(schema = Schema(ref = "#/components/schemas/InternalServerError"))]),
     ],

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

@@ -33,7 +33,7 @@ class DynamicRisksController(
   @Operation(
     summary = "Returns dynamic risks associated with a person.",
     responses = [
-      ApiResponse(responseCode = "200", description = "Successfully found dynamic risks for a person with the provided HMPPS ID."),
+      ApiResponse(responseCode = "200", useReturnTypeSchema = true, description = "Successfully found dynamic risks for a person with the provided HMPPS ID."),
       ApiResponse(responseCode = "404", content = [Content(schema = Schema(ref = "#/components/schemas/PersonNotFound"))]),
       ApiResponse(responseCode = "500", content = [Content(schema = Schema(ref = "#/components/schemas/InternalServerError"))]),
     ],

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

@@ -30,7 +30,7 @@ class LicenceConditionController(
   @Operation(
     summary = "Returns license conditions associated with a person, sorted by createdDateTime (newest first).",
     responses = [
-      ApiResponse(responseCode = "200", description = "Successfully found licenses for a person with the provided HMPPS ID."),
+      ApiResponse(responseCode = "200", useReturnTypeSchema = true, description = "Successfully found licenses for a person with the provided HMPPS ID."),
       ApiResponse(responseCode = "404", content = [Content(schema = Schema(ref = "#/components/schemas/PersonNotFound"))]),
       ApiResponse(responseCode = "500", content = [Content(schema = Schema(ref = "#/components/schemas/InternalServerError"))]),
     ],

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

@@ -30,7 +30,7 @@ class MappaDetailController(
   @Operation(
     summary = "Returns the mappa detail related to a person.",
     responses = [
-      ApiResponse(responseCode = "200", description = "Successfully found mappa detail for a person with the provided HMPPS ID."),
+      ApiResponse(responseCode = "200", useReturnTypeSchema = true, description = "Successfully found mappa detail for a person with the provided HMPPS ID."),
       ApiResponse(responseCode = "404", content = [Content(schema = Schema(ref = "#/components/schemas/PersonNotFound"))]),
       ApiResponse(responseCode = "500", content = [Content(schema = Schema(ref = "#/components/schemas/InternalServerError"))]),
     ],

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

@@ -35,7 +35,7 @@ class NeedsController(
             However, the process by which needs are assessed is changing as early as next year (2024), specifically moving to a strength-based model that seeks to identify and develop the strengths of people with convictions. As a consequence of this, the information provided by this endpoint will also change.
     """,
     responses = [
-      ApiResponse(responseCode = "200", description = "Successfully found criminogenic needs for a person with the provided HMPPS ID."),
+      ApiResponse(responseCode = "200", useReturnTypeSchema = true, description = "Successfully found criminogenic needs for a person with the provided HMPPS ID."),
       ApiResponse(responseCode = "404", content = [Content(schema = Schema(ref = "#/components/schemas/PersonNotFound"))]),
       ApiResponse(responseCode = "500", content = [Content(schema = Schema(ref = "#/components/schemas/InternalServerError"))]),
     ],

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

@@ -43,6 +43,7 @@ class OffencesController(
         description = "Successfully found offences for a person with the provided HMPPS ID.",
         content = [
           Content(
+            schema = Schema(implementation = PaginatedResponse::class),
             examples = [
               ExampleObject(
                 """{

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

@@ -46,7 +46,7 @@ class PersonController(
   @Operation(
     summary = "Returns person(s) by search criteria, sorted by date of birth (newest first). At least one query parameter must be specified.",
     responses = [
-      ApiResponse(responseCode = "200", description = "Successfully performed the query on upstream APIs. An empty list is returned when no results are found."),
+      ApiResponse(responseCode = "200", useReturnTypeSchema = true, description = "Successfully performed the query on upstream APIs. An empty list is returned when no results are found."),
       ApiResponse(
         responseCode = "400",
         description = "There were no query parameters passed in. At least one must be specified.",
@@ -85,7 +85,7 @@ class PersonController(
   @Operation(
     summary = "Returns a person.",
     responses = [
-      ApiResponse(responseCode = "200", description = "Successfully found a person with the provided HMPPS ID."),
+      ApiResponse(responseCode = "200", useReturnTypeSchema = true, description = "Successfully found a person with the provided HMPPS ID."),
       ApiResponse(responseCode = "404", content = [Content(schema = Schema(ref = "#/components/schemas/PersonNotFound"))]),
       ApiResponse(responseCode = "500", content = [Content(schema = Schema(ref = "#/components/schemas/InternalServerError"))]),
     ],
@@ -109,7 +109,7 @@ class PersonController(
   @Operation(
     summary = "Returns metadata of images associated with a person sorted by captureDateTime (newest first).",
     responses = [
-      ApiResponse(responseCode = "200", description = "Successfully found a person with the provided HMPPS ID. If a person doesn't have any images, then an empty list (`[]`) is returned in the `data` property."),
+      ApiResponse(responseCode = "200", useReturnTypeSchema = true, description = "Successfully found a person with the provided HMPPS ID. If a person doesn't have any images, then an empty list (`[]`) is returned in the `data` property."),
       ApiResponse(responseCode = "404", content = [Content(schema = Schema(ref = "#/components/schemas/PersonNotFound"))]),
       ApiResponse(responseCode = "500", content = [Content(schema = Schema(ref = "#/components/schemas/InternalServerError"))]),
     ],
@@ -135,7 +135,7 @@ class PersonController(
   @Operation(
     summary = "Returns a person's name",
     responses = [
-      ApiResponse(responseCode = "200", description = "Successfully found a person with the provided HMPPS ID."),
+      ApiResponse(responseCode = "200", useReturnTypeSchema = true, description = "Successfully found a person with the provided HMPPS ID."),
       ApiResponse(responseCode = "404", content = [Content(schema = Schema(ref = "#/components/schemas/PersonNotFound"))]),
       ApiResponse(responseCode = "500", content = [Content(schema = Schema(ref = "#/components/schemas/InternalServerError"))]),
     ],

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

@@ -32,7 +32,7 @@ class PersonResponsibleOfficerController(
   @Operation(
     summary = "Returns the person responsible officer associated with a person.",
     responses = [
-      ApiResponse(responseCode = "200", description = "Successfully found the person responsible officer for a person with the provided HMPPS ID."),
+      ApiResponse(responseCode = "200", useReturnTypeSchema = true, description = "Successfully found the person responsible officer for a person with the provided HMPPS ID."),
       ApiResponse(responseCode = "404", content = [Content(schema = Schema(ref = "#/components/schemas/PersonNotFound"))]),
       ApiResponse(responseCode = "500", content = [Content(schema = Schema(ref = "#/components/schemas/InternalServerError"))]),
     ],

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

@@ -30,7 +30,7 @@ class ProtectedCharacteristicsController(
   @Operation(
     summary = "Returns protected characteristics of a person.",
     responses = [
-      ApiResponse(responseCode = "200"),
+      ApiResponse(responseCode = "200", useReturnTypeSchema = true),
       ApiResponse(responseCode = "404", content = [Content(schema = Schema(ref = "#/components/schemas/PersonNotFound"))]),
       ApiResponse(responseCode = "500", content = [Content(schema = Schema(ref = "#/components/schemas/InternalServerError"))]),
     ],

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

@@ -30,7 +30,7 @@ class RiskCategoriesController(
   @Operation(
     summary = "Returns the categories related to an offender.",
     responses = [
-      ApiResponse(responseCode = "200", description = "Successfully found risk categories for a person with the provided HMPPS ID."),
+      ApiResponse(responseCode = "200", useReturnTypeSchema = true, description = "Successfully found risk categories for a person with the provided HMPPS ID."),
       ApiResponse(responseCode = "404", content = [Content(schema = Schema(ref = "#/components/schemas/PersonNotFound"))]),
       ApiResponse(responseCode = "500", content = [Content(schema = Schema(ref = "#/components/schemas/InternalServerError"))]),
     ],

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

@@ -32,7 +32,7 @@ class RiskPredictorScoresController(
   @Operation(
     summary = "Returns risk scores from the last year associated with a person, sorted by completedDate (newest first). This endpoint does not serve LAO (Limited Access Offender) data.",
     responses = [
-      ApiResponse(responseCode = "200", description = "Successfully found risk scores for a person with the provided HMPPS ID."),
+      ApiResponse(responseCode = "200", useReturnTypeSchema = true, description = "Successfully found risk scores for a person with the provided HMPPS ID."),
       ApiResponse(responseCode = "404", content = [Content(schema = Schema(ref = "#/components/schemas/PersonNotFound"))]),
       ApiResponse(responseCode = "500", content = [Content(schema = Schema(ref = "#/components/schemas/InternalServerError"))]),
     ],

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

@@ -30,7 +30,7 @@ class RiskSeriousHarmController(
   @Operation(
     summary = "Returns Risk of Serious Harm (ROSH) risks associated with a person. Returns only assessments completed in the last year. This endpoint does not serve LAO (Limited Access Offender) data.",
     responses = [
-      ApiResponse(responseCode = "200", description = "Successfully found risks for a person with the provided HMPPS ID."),
+      ApiResponse(responseCode = "200", useReturnTypeSchema = true, description = "Successfully found risks for a person with the provided HMPPS ID."),
       ApiResponse(responseCode = "404", content = [Content(schema = Schema(ref = "#/components/schemas/PersonNotFound"))]),
       ApiResponse(responseCode = "500", content = [Content(schema = Schema(ref = "#/components/schemas/InternalServerError"))]),
     ],