Start adding API description

[lornajane]

About this change - What it does

Adding API description in OpenAPI format so that we can test and mock the API, identify changes, and generate documentation.

References:

#181 <-- this isn't our first attempt at this, #255 was the previous one Fits with #402 , the work on the website (but is big enough that we probably don't want to stick them together. We can publish docs at some point from this description)

Why this way

OpenAPI is how we do API modernisation - and it also gives us docs. I'm working on the docs and might as well describe everything as I find it.