add descriptions to endpoints

Author: simonstead

specification/validated-relationships-service-api.yaml

@@ -478,7 +478,28 @@ paths:
 
     post:
       summary: Create a new FHIR Consent resource
-      description: Create a new Consent resource for RelatedPerson access
+      description: |
+        ## Overview
+        Use this endpoint to create a new proxy relationship between a patient and a related person (proxy). The request must include the necessary details about the relationship, evidence of responsibility, and requested access level.
+
+        ## Request Requirements
+        * The performer must be specified using a valid NHS Number
+        * The patient must be specified using a valid NHS Number
+        * Evidence of responsibility must be provided (e.g., birth certificate for parental relationships)
+        * The requested access level must be specified
+        * For child proxy requests, the child's age must be under 16
+        * For adult proxy requests, evidence of capacity assessment may be required
+
+        ## Sandbox test scenarios
+        | Scenario | Request | Response |
+        | -------- | ------- | -------- |
+        | Successful parent-child proxy creation | Valid request with parental relationship and birth certificate evidence | HTTP Status 201 and Bundle containing created Consent resource |
+        | Successful adult-adult proxy creation | Valid request with appropriate relationship and evidence | HTTP Status 201 and Bundle containing created Consent resource |
+        | Invalid performer NHS number | Request with invalid NHS number format | HTTP Status 400 and INVALID_NHS_NUMBER error response |
+        | Missing required evidence | Request without evidence of responsibility | HTTP Status 422 and MISSING_EVIDENCE error response |
+        | Invalid access level | Request with undefined access level code | HTTP Status 400 and INVALID_ACCESS_LEVEL error response |
+        | Patient age validation failure | Request for child proxy where child is over 16 | HTTP Status 422 and INVALID_PATIENT_AGE error response |
+        | Duplicate relationship | Request for relationship that already exists | HTTP Status 409 and DUPLICATE_RELATIONSHIP error response |
       requestBody:
         required: true
         content:
@@ -637,7 +658,33 @@ paths:
 
     patch:
       summary: Update an existing Consent resource
-      description: Modify a Consent resource using FHIR patch operation
+      description: | ## Overview
+        Use this endpoint to update an existing proxy relationship. This can be used to modify the status, access levels, or other attributes of the relationship. The update is performed using JSON Patch operations.
+
+        Common update scenarios include:
+        * Changing the status of a relationship
+        * Modifying access levels
+        * Adding or updating verification information
+        * Updating the validity period
+        * Adding or removing specific provisions
+
+        ## Request Requirements
+        * The Consent resource must exist and be identified by a valid identifier
+        * JSON Patch operations must be valid according to RFC 6902
+        * Status changes must use valid status codes from http://hl7.org/fhir/consent-state-codes
+        * Access level changes must use valid codes from the NHS proxy access level system
+
+        ## Sandbox test scenarios
+        | Scenario | Request | Response |
+        | -------- | ------- | -------- |
+        | Successful status update | Valid patch changing status to 'active' | HTTP Status 200 and updated Bundle |
+        | Successful access level update | Valid patch modifying access provisions | HTTP Status 200 and updated Bundle |
+        | Multiple valid changes | Valid patch with multiple operations | HTTP Status 200 and updated Bundle |
+        | Invalid patch format | Malformed JSON patch document | HTTP Status 400 and INVALID_PATCH_FORMAT error response |
+        | Invalid path | Patch targeting non-existent element | HTTP Status 400 and INVALID_PATCH_PATH error response |
+        | Invalid status code | Patch with invalid status value | HTTP Status 422 and INVALID_STATUS_CODE error response |
+        | Resource not found | Patch for non-existent Consent | HTTP Status 404 and RESOURCE_NOT_FOUND error response |
+        | Invalid state transition | Patch attempting invalid status change | HTTP Status 422 and INVALID_STATE_TRANSITION error response |
       parameters:
         - name: identifier
           in: query