[patient] Updated docs for 'contactList' to match current implementation.

paths/patient_contactList.yaml

@@ -7,18 +7,41 @@ get:
   parameters: 
     - name: patUnids
       in: query
+      mandatory: true
       description: |-
-        A comma separated list of patUnid's. For each patUnid the contact details are in the response. On a query string there is no standardized limit, but in practice the list of unid's might be limited to approximate 512 id's.
+        A comma separated list of patUnid values, as provided by other API endpoints.
+        For each patUnid the contact details are in the response. If sending lots of patUnids, we suggest you call this API in a POST (which is also allowed, though the semantic intent of this method is GET: It only queries and makes no changes) to avoid HTTP limits on query length.
       schema:
         type: array
         items:
           $ref: ../schemas/pat-patUnid.yaml
-        maxItems: 512
         example: "1234,5678"
+    - name: fields
+      in: query
+      mandatory: true
+      description: |-
+        Comma separated list of data fields that shold be returned in the response. Available options are:
+        bsn         - adds CSV column/JSON key 'bsn'.
+        patPubId    - adds CSV column/JSON key 'patPubId'.
+        patUnid     - adds CSV column/JSON key 'patUnid'.
+        gender      - adds CSV column/JSON key 'gender', with values 'O', 'M', or 'F'.
+        displayName - adds CSV column/JSON key 'displayName' with the full name of the patient as one would write it on an envelope.
+        fullName    - adds CSV columns 'initials', 'firstNames', 'infixOwn', 'ownLastName', 'infixPartner', 'partnerLastName', and JSON key 'name' with as value an object with those keys.
+        addressLine - adds CSV column/JSON key 'addressLine'.
+        postcode    - adds CSV column/JSON key 'postcode'.
+        city        - adds CSV column/JSON key 'city'.
+        tel         - adds CSV column/JSON key 'tel'.
+        email       - adds CSV column/JSON key 'email'.
+        dob         - adds CSV column/JSON key 'dob'.
+
+        See the descriptions in the JSON output section of this documentation for the formatting of these outputs.
+      example: "displayName,addressLine,postcode,city"
     - name: Accept
       in: header
       description: |-
-        CSV (RFC 4180) or JSON is responded depending on the preference set by the callers HTTP Accept header. The Accept header is processed according RFC 9110. If one of media-types below has the most weight, then that type will be the content-type of the response. This is always the case when the header equals one of the enumerated types.
+        This API is capable of emitting both CSV (RFC 4180) and JSON. If a CSV response is needed, ensure mimetype `text/csv` is
+        mentioned in the `Accept` header at a higher quality than `application/csv`. If no Accept header is provided, the API
+        responds with JSON.
       schema: 
         type: string
         enum: 
@@ -26,7 +49,8 @@ get:
           - application/json
   responses:
     '200':
-      description: A patient contact list for (electronic) mailing or phone contact. The list can be responded as CSV or JSON.
+      description: |-
+        A patient contact list for (electronic) mailing or phone contact. Per patient only requested details (via `column`) are provided. Any patient that isn't found isn't included in the output.
       headers:
         Content-Type:
           description: The actual content-type of the response.
@@ -39,12 +63,16 @@ get:
             items: 
               type: object
               properties:
-                patPubId:
-                  $ref: '../schemas/PatIdentity.yaml#/patPubId'
                 patUnid:
                   $ref: '../schemas/PatIdentity.yaml#/patUnid'
+                patPubId:
+                  $ref: '../schemas/PatIdentity.yaml#/patPubId'
+                gender:
+                  $ref: '../schemas/PatIdentity.yaml#/gender'
                 displayName:
                   $ref: '../schemas/pat-Name.yaml#/properties/displayName'
+                name:
+                  $ref: '../schemas/PatIdentity.yaml#/name'
                 addressLine:
                   description: The concatenation of street, housenumber and -suffix on one line.
                   type: string
@@ -56,13 +84,20 @@ get:
                   $ref: '../schemas/PatIdentity.yaml#/contact/properties/tel'
                 email:
                   $ref: '../schemas/PatIdentity.yaml#/contact/properties/email'
+                bsn:
+                  $ref: '../schemas/PatIdentity.yaml#/bsn'
+                dob:
+                  $ref: '../schemas/PatIdentity.yaml#/dob'
         text/csv:
           schema: 
             type: string
+            description: |-
+              An RFC4180 (with comma separator) output, with headers as requested.
     '400':
-      description: The request is invalid; for example, it doesn't contain the required `patUnids` parameter.
+      description: The request is invalid; for example, it doesn't contain the required `patUnids` or `columns` parameter.
     '401':
       $ref: '../zoo-api.yaml#/components/responses/JwtFailure'
-    '404':
-      $ref: '../zoo-api.yaml#/components/responses/PatNotFound'
-              
+    '406':
+      description: |-
+        An accept header was sent, but neither `text/csv` nor `application/json` is allowed by it.
+        As this endpoint can only render its data in those two content types, no response is possible.

zoo-api.yaml

@@ -169,6 +169,9 @@ components:
         items: 
           $ref: schemas/med_dossier/Practitioner.yaml
   responses:
+    NotAcceptable:
+      description: |-
+        The Accept header as sent by the requestor and the types of content this endpoint can emit have no overlap and thus no response is possible.
     ReqFailure:
       description: The request isn't valid; for example, it is missing a required parameter.
       content: