Document that create visit endpoint creates an approved visit (#777)

* Remove documentation that does not apply to our API.

* Update summaries of endpoints to make clearer that they are reporting external systems.

* Add warning of no checking of the visit suitability.

* Remove superfluous breaks.

* Provide more detail on return value of visitor restrictions.

* Reword future visits endpoint summary.

* Reword prisoner visit-restrictions endpoint.

* Reword visit-orders summary.

* Bring description onto one line to fix generated html.

* Remove double brs

* Typo.

Author: ben-madley-mt

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

@@ -60,10 +60,7 @@ class HmppsIdController(
   @GetMapping("nomis-number/by-hmpps-id/{hmppsId}")
   @Operation(
     summary = "Return nomis number for a given HMPPS Id",
-    description = """
-      Accepts a HMPPS Id (hmppsId) and looks up the corresponding nomis number.<br>
-      <b>Applicable filters</b>: <ul><li>prisons</li></ul>
-    """,
+    description = "Accepts a HMPPS Id (hmppsId) and looks up the corresponding nomis number.<br><b>Applicable filters</b>: <ul><li>prisons</li></ul>",
     responses = [
       ApiResponse(responseCode = "200", useReturnTypeSchema = true),
       ApiResponse(responseCode = "404", description = "Nomis number could not be found."),

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

@@ -31,7 +31,7 @@ class OffenderRestrictionsController(
   @GetMapping("/v1/prison/{prisonId}/prisoners/{hmppsId}/non-associations")
   @Operation(
     summary = "Returns a single prisoners list of non associates.",
-    description = "<b>Applicable filters</b>: <ul><li>prisons</li></ul> <br> includeOpen is true by default, includeClosed is false by default. At least one must be true. The role READ_NON_ASSOCIATIONS is required for this endpoint.",
+    description = "<b>Applicable filters</b>: <ul><li>prisons</li></ul> <br> includeOpen is true by default, includeClosed is false by default. At least one must be true.",
     responses = [
       ApiResponse(responseCode = "200", useReturnTypeSchema = true, description = "Successfully found prisoners non associates."),
       ApiResponse(

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

@@ -182,7 +182,7 @@ class TransactionsController(
 
   @Operation(
     summary = "Make a financial transaction.",
-    description = "<a href=\"#schema-transactionrequest\">Request body</a><br><br><b>Applicable filters</b>: <ul><li>prisons</li></ul>",
+    description = "<a href=\"#schema-transactionrequest\">Request body</a><br><b>Applicable filters</b>: <ul><li>prisons</li></ul>",
     responses = [
       ApiResponse(responseCode = "200", useReturnTypeSchema = true, description = "Successfully created a transaction."),
       ApiResponse(
@@ -255,7 +255,7 @@ class TransactionsController(
 
   @Operation(
     summary = "Transfer funds between the accounts of a prisoner.",
-    description = "Currently only able to move from spends to savings.<br><br><a href=\"#schema-transactiontransferrequest\">Request body</a><br><br><b>Applicable filters</b>: <ul><li>prisons</li></ul>",
+    description = "Currently only able to move from spends to savings.<br><a href=\"#schema-transactiontransferrequest\">Request body</a><br><br><b>Applicable filters</b>: <ul><li>prisons</li></ul>",
     responses = [
       ApiResponse(responseCode = "200", useReturnTypeSchema = true, description = "Successfully created a transaction transfer."),
       ApiResponse(

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

@@ -37,7 +37,7 @@ class VisitsController(
 ) {
   @Operation(
     summary = "Get visit information for a visit by visit reference.",
-    description = "<br><br><b>Applicable filters</b>: <ul><li>prisons</li></ul>",
+    description = "<b>Applicable filters</b>: <ul><li>prisons</li></ul>",
     responses = [
       ApiResponse(responseCode = "200", useReturnTypeSchema = true, description = "Successfully found visit information for a given visit reference."),
       ApiResponse(
@@ -80,8 +80,11 @@ class VisitsController(
   }
 
   @Operation(
-    summary = "Create visit.",
-    description = "<br><br><b>Applicable filters</b>: <ul><li>prisons</li></ul>",
+    summary = "Report the creation of a visit in an external system.",
+    description =
+      "This API only validates the existence of the entities included. It does not perform any checking of the suitability of the visit. " +
+        "That responsibility is left to the client." +
+        "<br><b>Applicable filters</b>: <ul><li>prisons</li></ul>",
     responses = [
       ApiResponse(responseCode = "200", useReturnTypeSchema = true, description = "Successfully wrote to visit queue."),
       ApiResponse(
@@ -138,8 +141,8 @@ class VisitsController(
   }
 
   @Operation(
-    summary = "Cancel visit.",
-    description = "<br><br><b>Applicable filters</b>: <ul><li>prisons</li></ul>",
+    summary = "Report the cancellation of a visit in an external system.",
+    description = "<b>Applicable filters</b>: <ul><li>prisons</li></ul>",
     responses = [
       ApiResponse(responseCode = "200", useReturnTypeSchema = true, description = "Successfully wrote to visit queue."),
       ApiResponse(

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

@@ -30,7 +30,7 @@ class FutureVisitsController(
   @Autowired val getFutureVisitsService: GetFutureVisitsService,
 ) {
   @Operation(
-    summary = "Get Future Visit Information.",
+    summary = "Get information about a prisoner's future visits.",
     description = "<b>Applicable filters</b>: <ul><li>prisons</li></ul>",
     responses = [
       ApiResponse(responseCode = "200", useReturnTypeSchema = true, description = "Successfully found a person's future visits with the provided HMPPS ID."),

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

@@ -235,7 +235,7 @@ class PersonController(
 
   @GetMapping("{hmppsId}/visit-orders")
   @Operation(
-    summary = "Returns visit orders.",
+    summary = "Returns the number of remaining visit orders a prisoner has.",
     responses = [
       ApiResponse(responseCode = "200", useReturnTypeSchema = true, description = "Successfully found a prisoners visit orders."),
       ApiResponse(responseCode = "404", content = [Content(schema = Schema(ref = "#/components/schemas/PersonNotFound"))]),

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

@@ -32,8 +32,8 @@ class VisitRestrictionsController(
   @Autowired val getVisitorRestrictionsService: GetVisitorRestrictionsService,
 ) {
   @Operation(
-    summary = "Gets restrictions for latest booking.",
-    description = "Returns a list of restrictions for the latest booking",
+    summary = "Gets visit restrictions for a prisoner.",
+    description = "Returns a prisoner's visit restrictions. Only returns the visit restrictions for the prisoner's most recent booking.",
     responses = [
       ApiResponse(responseCode = "200", useReturnTypeSchema = true, description = "Successfully found a person's visit restrictions with the provided HMPPS ID."),
       ApiResponse(responseCode = "400", content = [Content(schema = Schema(ref = "#/components/schemas/BadRequest"))]),
@@ -60,8 +60,8 @@ class VisitRestrictionsController(
   }
 
   @Operation(
-    summary = "Gets visitor restrictions.",
-    description = "Returns visitor restrictions for a prisoner",
+    summary = "Get the restrictions for a visitor.",
+    description = "Provides both the global restrictions for the visitor, as well as the restrictions for the relationship between the prisoner and visitor.",
     responses = [
       ApiResponse(responseCode = "200", useReturnTypeSchema = true, description = "Successfully found a prisoners vistor restrictions with the provided HMPPS ID and contact ID."),
       ApiResponse(responseCode = "400", content = [Content(schema = Schema(ref = "#/components/schemas/BadRequest"))]),