VED-942 Modify the update endpoint documentation (#1081)

Author: dlzhry2nhs

Makefile

@@ -32,6 +32,9 @@ publish: clean
 	cp build/immunisation-fhir-api.json sandbox/
 	cp -r specification sandbox/specification
 
+make serve: publish
+	npm run serve
+
 #Creates a minified OAS spec in JSON for sending to APIM
 oas: publish
 	mkdir -p oas

README.specification.md

@@ -55,12 +55,13 @@ There are `make` commands that alias some of this functionality:
 
 - `lint` -- Lints the spec and code
 - `publish` -- Outputs the specification as a **single** JSON file into the `build/` directory
+- `serve` -- Serves a preview of the API document locally
 
 ### Modifying the OAS file
 
 Note that the master OAS file is now the **YAML** version, as it is far easier to maintain than the JSON.
 
-To review your modifications, use Swagger Editor (https://editor.swagger.io).
+To review your modifications, use Swagger Editor (https://editor.swagger.io). Or, alternatively, use the `make serve` command.
 
 ### Update the OAS file to the public website
 

azure/templates/build.yml

@@ -4,7 +4,7 @@ steps:
       npm run publish 2> /dev/null
       cp build/immunisation-fhir-api.json sandbox/
 
-        cd sandbox
+      cd sandbox
       docker build -t sandbox .
     displayName: Build sandbox image
     workingDirectory: "$(Pipeline.Workspace)/s/$(SERVICE_NAME)"

infrastructure/proxies/sandbox/apiproxy/policies/AssignMessage.AddCors.xml

@@ -4,8 +4,8 @@
     <Set>
         <Headers>
             <Header name="Access-Control-Allow-Origin">{request.header.origin}</Header>
-            <Header name="Access-Control-Allow-Headers">origin, x-requested-with, accept, content-type, nhsd-session-urid, X-Request-Id, X-Correlation-Id, Location</Header>
-            <Header name="Access-Control-Expose-Headers">origin, x-requested-with, accept, content-type, nhsd-session-urid, X-Request-Id, X-Correlation-Id, Location</Header>
+            <Header name="Access-Control-Allow-Headers">origin, x-requested-with, accept, content-type, e-tag, nhsd-session-urid, X-Request-Id, X-Correlation-Id, Location</Header>
+            <Header name="Access-Control-Expose-Headers">origin, x-requested-with, accept, content-type, e-tag, nhsd-session-urid, X-Request-Id, X-Correlation-Id, Location</Header>
             <Header name="Access-Control-Max-Age">3628800</Header>
             <Header name="Access-Control-Allow-Methods">GET, PUT, POST, DELETE</Header>
         </Headers>

package.json

@@ -8,7 +8,8 @@
     "format-check": "prettier --check .",
     "publish": "redocly bundle specification/immunisation-fhir-api.yaml --remove-unused-components --ext json -o build/immunisation-fhir-api.json",
     "check-licenses": "node_modules/.bin/license-checker --failOn GPL --failOn LGPL",
-    "prepare": "husky"
+    "prepare": "husky",
+    "serve": "redocly preview --project-dir ./build"
   },
   "author": "NHS Digital",
   "license": "MIT",

specification/immunisation-fhir-api.yaml

@@ -2207,26 +2207,22 @@ paths:
       description: >
         ## Overview
 
-        This interaction allows you to add a new updated record of a vaccination
-        event. Update replaces the full immunization resource, so you must
-        provide all data fields, not just the change (Patch is not currently
-        supported). You may obtain all the current data for the vaccination
-        event using the read interaction, which will also return an eTag for the
-        version. 
+        The Update Immunization endpoint allows you to update or reinstate a vaccination event.
 
+        - You must provide the full FHIR immunization in the request body. (Patch is not currently
+        supported, so it is not possible to just provide the updated fields.)
 
-        You may use update to re-instate a deleted record, but our update
-        interaction does not support creating a new vaccination event where one
-        does not currently exist. 
+        - You may need to first retrieve the existing vaccination record using the GET endpoint, which
+        will also return an E-Tag header for the resource version. When performing an update, the E-Tag
+        header must match the current resource version for the resource you are updating.
 
+        - The `id` and `identifier` in the request body and the `id` in the path parameters must match
+        the existing record for an update to succeed.
 
-        You must not change the identifier when updating a vaccination event.
-        The identifier is used as a primary identifier by downstream systems.  
-
-
-        You must be authorised for update interaction and the disease type
-        associated with the vaccination event in order to update the record. 
+        - You may also use this endpoint to reinstate a deleted record.
 
+        - Finally, you must be authorised for the update interaction and the vaccination type of the
+        existing record in order for the update to succeed.
 
         ## Sandbox testing        
 
@@ -4610,6 +4606,7 @@ components:
                 description: >
                   Specific procedures, disorders, diseases, infections or
                   organisms.
+                example: FLU
                 enum:
                   - 3IN1
                   - COVID
@@ -4714,6 +4711,7 @@ components:
       required: true
       schema:
         type: string
+        example: FLU
         enum:
           - 3IN1
           - COVID