Improve the server key exchange portion of the s2s specification

Most of the text has been shuffled into the swagger definitions to bring it closer to where it matters.

This also attempts to clarify what is out in the wild. Most importantly, the first version of the key exchange is outright removed from the specification. Other research points/questions are:

* What is a "Key ID"?
  * 1241156c82/synapse/rest/key/v2/local_key_resource.py (L81-L83)
  * 1241156c82/synapse/rest/key/v2/local_key_resource.py (L88-L91)
* Returning a cached response if the server throws a 400, 500, or otherwise not-offline status code
  * 1241156c82/synapse/rest/key/v2/remote_key_resource.py (L227-L229)
* `minimum_valid_until_ts` default
  * This branch of the ladder: 1241156c82/synapse/rest/key/v2/remote_key_resource.py (L192)
* Returning empty arrays when querying offline/no servers
  * Queried by hand against matrix.org as a notary server with a fake domain name to query
* Returning all keys even when querying for specific keys
  * Queried by hand using matrix.org as a notary server against a server publishing multiple keys.

The examples and descriptions were also improved as part of this commit.

api/server-server/keys_server.yaml

@@ -25,18 +25,38 @@ produces:
 paths:
   "/server/{keyId}":
     get:
-      summary: Get the server's key
-      description: Get the server's key.
+      summary: Get the homeserver's public key(s)
+      description: |-
+        Gets the homeserver's published TLS fingerprints and signing keys.
+        The homeserver may have any number of active keys and may have a
+        number of old keys. Homeservers SHOULD return a single JSON object
+        listing all of its keys, regardless of the ``keyId`` path argument.
+        This is to reduce the number of round trips needed to discover the
+        relevant keys for a homeserver.
+
+        Intermediate notary servers should cache a response for half of its
+        lifetime to avoid serving a stale response. Originating servers should
+        avoid returning responses that expire in less than an hour to avoid
+        repeated reqests for a certificate that is about to expire. Requesting
+        servers should limit how frequently they query for certificates to
+        avoid flooding a server with requests.
+
+        If the server fails to respond to this request, intermediate notary
+        servers should continue to return the last response they received
+        from the server so that the signatures of old events can still be
+        checked.
       operationId: getServerKey
       parameters:
         - in: path
           name: keyId
           type: string
-          description: Key ID
+          description: |-
+            The key ID to look up. If omitted or empty, all server keys are
+            to be returned.
           required: false
-          x-example: TODO # No examples in the spec so far
+          x-example: "ed25519:abc123"
       responses:
         200:
-          description: The server's keys.
+          description: The homeserver's keys
           schema:
             $ref: "definitions/keys.yaml"