Clarify the key object definition for the key management API

[turt2live]

Fixes #1907

[turt2live]

It's very annoying that Swagger doesn't support the thing we want to do (anyOf on a response schema). It supports it just fine for request parameters, but not in the response schema for some reason.

Error is the cryptic:

JSON_OBJECT_VALIDATION_FAILED",
  "stack": "SyntaxError: Swagger schema validation failed.
  Data does not match any schemas from 'oneOf' at #/paths//keys/claim/post/responses/200
    Data does not match any schemas from 'oneOf' at #/paths//keys/claim/post/responses/200/schema
      Data does not match any schemas from 'anyOf' at #/schema/properties/one_time_keys/additionalProperties
        Data does not match any schemas from 'anyOf' at #/properties/one_time_keys/additionalProperties/additionalProperties
          Data does not match any schemas from 'anyOf' at #/additionalProperties/type
            No enum match for: string,[object Object] at #/type
            No enum match for: {\"type\":\"object\",\"title\":\"KeyObject\",\"properties\":{\"key\":{\"type\":\"string\",\"description\":\"The key, encoded using unpadded base64.\"},\"signatures\":{\"type\":\"object\",\"description\":\"Signature for the device. Mapped from user ID to signature object.\",\"additionalProperties\":{\"type\":\"string\"}}},\"required\":[\"key\",\"signatures\"]} at #/type/1
          Expected type boolean but found type object at #/additionalProperties
        Expected type boolean but found type object at #/properties/one_time_keys/additionalProperties
      Additional properties not allowed: properties at #/schema
    Missing required property: $ref at #/paths//keys/claim/post/responses/200

Edit: our rendering engine can figure it out (which is why it is defined as such in the s2s spec), however we'll run into problems when https://github.com/matrix-org/matrix-doc/issues/2085 gets implemented. I'm inclined to just fork that problem off to that issue though rather than hide a swagger definition in both specs.

[ara4n]

errrm... looks like swagger. maybe? possibly? </dog_goggles>

[turt2live]

It's definitely swagger, although the diff (and swagger, annoyingly) is very confusing. It's supposed to be fix the nesting levels while also making documentation a thing.

[uhoreg]

Something isn't happy in CS /keys/upload:

[uhoreg]

The content looks good. The structure (other than the error message from the above comment) looks plausible, though I'm not a swagger expert. Should be fine to merge once the error is fixed.

[uhoreg]

made a suggestion, but lgtm otherwise