VED-993 Fix error responses in API specification

[dlzhry2nhs]

Summary

• Routine Change

Primary change was to fix the schema for the OperationOutcome error responses. If you check the schema for any of the 4XX errors on our page, you will notice they are wrong and contain loads of superfluous information: https://digital.nhs.uk/developer/api-catalogue/immunisation-fhir-api#get-/Immunization

I have based my changes on the PDS FHIR API - https://digital.nhs.uk/developer/api-catalogue/personal-demographics-service-fhir#post-/Patient where the schema and examples reflect what the API does.

As an aside, when cross-referencing what we do against the actual FHIR specification, there are several problems. We can think about how/if we want to address this under VED-857.

Summary of changes:

• Single correct schema and example now in use for all 4XX errors.
• Corrected the tables to reflect the actual code we will get back from the API for the different scenarios.
• Added a 500 example to each of the endpoints.
• Deleted all the obsolete schema items which were added (by AI?) for no good reason.

Reviews Required

• Dev
• Tech Author

Review Checklist

ℹ️ This section is to be filled in by the reviewer.

• I have reviewed the changes in this PR and they fill all of the acceptance criteria of the ticket.
• If there were infrastructure, operational, or build changes, I have made sure there is sufficient evidence that the changes will work.
• If there were changes that are outside of the regular release processes e.g. account infrastructure to setup, manual setup for external API integrations, secrets to set, then I have checked that the developer has flagged this to the Tech Lead as release steps.
• I have checked that no Personal Identifiable Data (PID) is logged as part of the changes.

[github-actions]

This branch is working on a ticket in the NHS England VED JIRA Project. Here's a handy link to the ticket:

VED-993

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[mfjarvis]

I like what you've done in the 4XX-imms-create section above, consolidating multiple entries for various different flavours of validation error into a single entry. Perhaps we should do something similar here - it seems a bit unnecessary to state all of the different parameters which could contain an invalid value. A single entry of "Invalid or missing search parameter" would suffice