Re-worked OpenAPI spec (CADC 15042)

[andamian]

Renamed branch

[pdowler]

parameter definition style:

I found one of:

- name: groupID
  in: path
...

or (eg)

- $ref: {defined elsewhere}

to be the most compact. See VOSI.git for examples of params defined in separate files.

Having

groupID:
  name: groupID
...

is either redundant or confusing when the two values differ.

[andamian]

That works in service parameters but not in components. In components the first occurrence is a key and the second one is the name. Although appears to be a repetition, that is not necessarily so as we could use a different value such as groupIDKey for example. Would that make the intention more obvious?