Look for examples in all possible locations

[zecakeh]

We used to only look for examples in a few (sometimes arbitrary) places, and we didn't support showing several examples in most cases. This is intended to fix this. In the process we try to deduplicate code to make sure that we use the same logic everywhere.

This can be reviewed commit by commit:

1. Deduplicate code to render examples. Since there is some logic necessary for "JSONification", notably decoding < and > inside examples, it's better to keep it in a single place. We also centralize the support for non-JSON examples by using the no-highlight value.
2. Change the json-schema/resolve-example partial to return a slice of examples, and to look also at the examples key, which is the correct key for examples in JSON Schema.
3. Deduplicate code between requests and responses by identifying what the OpenAPI spec calls "Media Type Objects". In the process we also look in more places, like the examples key once again, given that the example key is deprecated. And we unify the order of the locations where we look, by using the full examples before we try to generate one from the examples of the fields. This produces only a few changes in the rendered spec (see below).
4. Fix a few SS API examples that are now picked up to be rendered in the spec, that contain a room_id field although it is not in the corresponding definition.
5. Only show empty examples if the object is empty. Fixes Empty objects and null in registration arrays #1811.

Closes #1157.

Changes in the rendered spec

The only changes are located in the SS API. Other than a few minor changes in the values of fields (like using example.org instead of matrix.org) in several examples, the 2 following examples for the /invite endpoints have significant changes:

PUT /_matrix/federation/v1/invite/{roomId}/{eventId}'s request body example:

Before:

{
  "content": {
    "membership": "invite"
  },
  "origin": "matrix.org",
  "origin_server_ts": 1234567890,
  "sender": "@someone:example.org",
  "state_key": "@joe:elsewhere.com",
  "type": "m.room.member",
  "unsigned": {
    "invite_room_state": [
      {
        "content": {
          "name": "Example Room"
        },
        "sender": "@bob:example.org",
        "state_key": "",
        "type": "m.room.name"
      },
      {
        "content": {
          "join_rule": "invite"
        },
        "sender": "@bob:example.org",
        "state_key": "",
        "type": "m.room.join_rules"
      }
    ]
  }
}

After:

{
  "content": {
    "membership": "invite"
  },
  "origin": "example.org",
  "origin_server_ts": 1549041175876,
  "sender": "@someone:example.org",
  "signatures": {
    "example.com": {
      "ed25519:key_version": "SomeSignatureHere"
    }
  },
  "state_key": "@joe:elsewhere.com",
  "type": "m.room.member"
}

PUT /_matrix/federation/v2/invite/{roomId}/{eventId}'s request body example:

Before:

{
  "event": {
    "content": {
      "membership": "invite"
    },
    "origin": "matrix.org",
    "origin_server_ts": 1234567890,
    "sender": "@someone:example.org",
    "state_key": "@joe:elsewhere.com",
    "type": "m.room.member"
  },
  "invite_room_state": [
    {
      "content": {
        "name": "Example Room"
      },
      "sender": "@bob:example.org",
      "state_key": "",
      "type": "m.room.name"
    },
    {
      "content": {
        "join_rule": "invite"
      },
      "sender": "@bob:example.org",
      "state_key": "",
      "type": "m.room.join_rules"
    }
  ],
  "room_version": "2"
}

After:

{
  "event": {
    "content": {
      "membership": "invite"
    },
    "origin": "example.org",
    "origin_server_ts": 1549041175876,
    "sender": "@someone:example.org",
    "signatures": {
      "example.com": {
        "ed25519:key_version": "SomeSignatureHere"
      }
    },
    "state_key": "@joe:elsewhere.com",
    "type": "m.room.member"
  },
  "room_version": "2"
}

In both cases, the invite_room_state is removed, and signatures is added. I believe that the old example is better so we could just remove those examples.

Pull Request Checklist

• Pull request includes a changelog file
• Pull request includes a sign off
• Pull request is classified as 'other changes'

Preview: https://pr2076--matrix-spec-previews.netlify.app

[richvdh]

In both cases, the invite_room_state is removed, and signatures is added. I believe that the old example is better so we could just remove those examples.

yes, the loss of invite_room_state isn't ideal here.

[richvdh]

lgtm otherwise

[zecakeh]

I removed the global examples of the PUT /invite endpoints to use the ones generated from the fields, like before.

[richvdh]

thanks