Clean up identity service swagger

* Add `consumes` (swagger)
* Remove `http` as a supported scheme (the spec specifically says clients MUST use https)
* Clarify various descriptions
  * Full stops
  * Additional wording
  * s/older versions/previous drafts - we haven't had a release yet
* Indentation on examples

api/identity/associations.yaml

@@ -18,15 +18,17 @@ info:
 host: localhost:8090
 schemes:
   - https
-  - http
 basePath: /_matrix/identity/api/v1
+consumes:
+  - application/json
 produces:
   - application/json
 paths:
   "/3pid/getValidated3pid":
     get:
       summary: Check whether ownership of a 3pid was validated.
-      description: A client can check whether ownership of a 3pid was validated
+      description: |-
+        Determines if a given 3pid has been validated by a user.
       operationId: getValidated3pid
       parameters:
         - in: query
@@ -61,7 +63,9 @@ paths:
                 description: The address of the 3pid being looked up.
               validated_at:
                 type: integer
-                description: Timestamp indicating the time that the 3pid was validated.
+                description: |-
+                  Timestamp, in milliseconds, indicating the time that the 3pid
+                  was validated.
             required: ['medium', 'address', 'validated_at']
         400:
           description: |-
@@ -78,7 +82,7 @@ paths:
           schema:
             $ref: "../client-server/definitions/errors/error.yaml"
         404:
-          description: The Session ID or client secret were not found
+          description: The Session ID or client secret were not found.
           examples:
             application/json: {
               "errcode": "M_NO_VALID_SESSION",
@@ -95,7 +99,7 @@ paths:
         Future calls to ``/lookup`` for any of the session\'s 3pids will return
         this association.
 
-        Note: for backwards compatibility with older versions of this
+        Note: for backwards compatibility with previous drafts of this
         specification, the parameters may also be specified as
         ``application/x-form-www-urlencoded`` data.  However, this usage is
         deprecated.
@@ -132,7 +136,6 @@ paths:
               "not_before": 1428825849161,
               "not_after": 4582425849161,
               "ts": 1428825849161,
-
               "signatures": {
                 "matrix.org": {
                   "ed25519:0": "ENiU2YORYUJgE6WBMitU0mppbQjidDLanAusj8XS2nVRHPu+0t42OKA/r6zV6i2MzUbNQ3c3MiLScJuSsOiVDQ"
@@ -162,7 +165,10 @@ paths:
                 description: The unix timestamp at which the association was verified.
               signatures:
                 type: object
-                description: The signatures of the verifying identity services which show that the association should be trusted, if you trust the verifying identity services.
+                description: |-
+                  The signatures of the verifying identity services which show that the
+                  association should be trusted, if you trust the verifying identity
+                  services.
                 $ref: "../../schemas/server-signatures.yaml"
             required:
               - address

api/identity/email_associations.yaml

@@ -18,8 +18,9 @@ info:
 host: localhost:8090
 schemes:
   - https
-  - http
 basePath: /_matrix/identity/api/v1
+consumes:
+  - application/json
 produces:
   - application/json
 paths:
@@ -34,13 +35,13 @@ paths:
         that that user was able to read the email for that email address, and
         so we validate ownership of the email address.
 
-        Note that Home Servers offer APIs that proxy this API, adding
+        Note that homeservers offer APIs that proxy this API, adding
         additional behaviour on top, for example,
         ``/register/email/requestToken`` is designed specifically for use when
         registering an account and therefore will inform the user if the email
         address given is already registered on the server.
 
-        Note: for backwards compatibility with older versions of this
+        Note: for backwards compatibility with previous drafts of this
         specification, the parameters may also be specified as
         ``application/x-form-www-urlencoded`` data.  However, this usage is
         deprecated.
@@ -58,7 +59,7 @@ paths:
             properties:
               client_secret:
                 type: string
-                description: A unique string used to identify the validation attempt
+                description: A unique string used to identify the validation attempt.
               email:
                 type: string
                 description: The email address to validate.
@@ -119,7 +120,7 @@ paths:
         associate the email address with any Matrix user ID. Specifically,
         calls to ``/lookup`` will not show a binding.
 
-        Note: for backwards compatibility with older versions of this
+        Note: for backwards compatibility with previous drafts of this
         specification, the parameters may also be specified as
         ``application/x-form-www-urlencoded`` data.  However, this usage is
         deprecated.

api/identity/invitation_signing.yaml

@@ -18,8 +18,9 @@ info:
 host: localhost:8090
 schemes:
   - https
-  - http
 basePath: /_matrix/identity/api/v1
+consumes:
+  - application/json
 produces:
   - application/json
 paths:
@@ -29,7 +30,7 @@ paths:
       description: |-
         Sign invitation details.
 
-        The identity server will look up ``token`` which was stored in a call
+        The identity service will look up ``token`` which was stored in a call
         to ``store-invite``, and fetch the sender of the invite.
       operationId: blindlySignStuff
       parameters:
@@ -38,24 +39,24 @@ paths:
           schema:
             type: object
             example: {
-                "mxid": "@foo:bar.com",
+              "mxid": "@foo:bar.com",
-                "token": "sometoken",
+              "token": "sometoken",
-                "private_key": "base64encodedkey"
+              "private_key": "base64encodedkey"
-              }
+            }
             properties:
               mxid:
                 type: string
                 description: The Matrix user ID of the user accepting the invitation.
               token:
                 type: string
-                description: Token from the call to ``store-invite``
+                description: The token from the call to ``store-invite``.
               private_key:
                 type: string
                 description: The private key, encoded as `Unpadded base64`_.
             required: ["mxid", "token", "private_key"]
       responses:
         200:
-          description: The signedjson of the mxid, sender, and token.
+          description: The signed JSON of the mxid, sender, and token.
           schema:
             type: object
             properties:
@@ -85,7 +86,7 @@ paths:
               "token": "abc123"
             }
         404:
-          description: Token was not found.
+          description: The token was not found.
           examples: 
             application/json: {
               "errcode": "M_UNRECOGNIZED",

api/identity/lookup.yaml

@@ -1,6 +1,7 @@
 # Copyright 2016 OpenMarket Ltd
 # Copyright 2017 Kamax.io
 # Copyright 2017 New Vector Ltd
+# Copyright 2018 New Vector Ltd
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -20,8 +21,9 @@ info:
 host: localhost:8090
 schemes:
   - https
-  - http
 basePath: /_matrix/identity/api/v1
+consumes:
+  - application/json
 produces:
   - application/json
 paths:
@@ -46,7 +48,7 @@ paths:
       responses:
         200:
           description:
-            The association for that 3pid, or the empty object if no association is known.
+            The association for that 3pid, or an empty object if no association is known.
           examples:
             application/json: {
               "address": "louise@bobs.burgers",
@@ -66,10 +68,10 @@ paths:
             properties:
               address:
                 type: string
-                description: The 3pid address of the user being looked up.
+                description: The 3pid address of the user being looked up, matching the address requested.
               medium:
                 type: string
-                description: The literal string "email".
+                description: A medium from the `3PID Types`_ Appendix, matching the medium requested.
               mxid:
                 type: string
                 description: The Matrix user ID associated with the 3pid.
@@ -126,7 +128,9 @@ paths:
                     #- type: 3PID Address
                     - type: string
                     - type: string
-                description: an array of arrays containing the `3PID Types`_ with the ``medium`` in first position and the ``address`` in second position.
+                description: |-
+                  An array of arrays containing the `3PID Types`_ with the ``medium``
+                  in first position and the ``address`` in second position.
             required:
               - "threepids"
       responses:
@@ -157,6 +161,9 @@ paths:
                     - type: string
                     - type: string
                     - type: string
-                description: an array of array containing the `3PID Types`_ with the ``medium`` in first position, the ``address`` in second position and Matrix ID in third position.
+                description: |-
+                  An array of array containing the `3PID Types`_ with the ``medium``
+                  in first position, the ``address`` in second position and Matrix user
+                  ID in third position.
             required:
               - "threepids"

api/identity/phone_associations.yaml

@@ -18,8 +18,9 @@ info:
 host: localhost:8090
 schemes:
   - https
-  - http
 basePath: /_matrix/identity/api/v1
+consumes:
+  - application/json
 produces:
   - application/json
 paths:
@@ -34,13 +35,13 @@ paths:
         indicates that that user was able to read the SMS for that phone
         number, and so we validate ownership of the phone number.
 
-        Note that Home Servers offer APIs that proxy this API, adding
+        Note that homeservers offer APIs that proxy this API, adding
         additional behaviour on top, for example,
         ``/register/msisdn/requestToken`` is designed specifically for use when
         registering an account and therefore will inform the user if the phone
         number given is already registered on the server.
 
-        Note: for backwards compatibility with older versions of this
+        Note: for backwards compatibility with previous drafts of this
         specification, the parameters may also be specified as
         ``application/x-form-www-urlencoded`` data. However, this usage is
         deprecated.
@@ -106,6 +107,8 @@ paths:
 
             - ``M_INVALID_ADDRESS``: The phone number provided was invalid.
             - ``M_SEND_ERROR``: The validation SMS could not be sent.
+            - ``M_DESTINATION_REJECTED``: The identity service cannot deliver an
+              SMS to the provided country or region.
           examples:
             application/json: {
               "errcode": "M_INVALID_ADDRESS",
@@ -125,7 +128,7 @@ paths:
         associate the phone number address with any Matrix user
         ID. Specifically, calls to ``/lookup`` will not show a binding.
 
-        Note: for backwards compatibility with older versions of this
+        Note: for backwards compatibility with previous drafts of this
         specification, the parameters may also be specified as
         ``application/x-form-www-urlencoded`` data. However, this usage is
         deprecated.

api/identity/ping.yaml

@@ -1,4 +1,5 @@
 # Copyright 2018 Kamax Sàrl
+# Copyright 2018 New Vector Ltd
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -14,7 +15,7 @@
 
 swagger: "2.0"
 info:
-  title: "Matrix Client-Identity Versions API"
+  title: "Matrix Identity Service Ping API"
   version: "1.0.0"
 host: localhost:8090
 schemes:
@@ -25,19 +26,19 @@ produces:
 paths:
   "/api/v1":
     get:
-      summary: Checks that an Identity server is available at this API endpopint.
+      summary: Checks that an Identity Service is available at this API endpoint.
       description: |-
-        Checks that an Identity server is available at this API endpopint.
+        Checks that an Identity Service is available at this API endpoint.
 
-        To discover that an Identity server is available at a specific URL,
+        To discover that an Identity Service is available at a specific URL,
         this endpoint can be queried and will return an empty object.
 
         This is primarly used for auto-discovery and health check purposes
-        by entities acting as a client for the Identity server.
+        by entities acting as a client for the Identity Service.
       operationId: ping
       responses:
         200:
-          description: An Identity server is ready to serve requests.
+          description: An Identity Service is ready to serve requests.
           examples:
             application/json: {}
           schema:

api/identity/pubkey.yaml

@@ -18,8 +18,9 @@ info:
 host: localhost:8090
 schemes:
   - https
-  - http
 basePath: /_matrix/identity/api/v1
+consumes:
+  - application/json
 produces:
   - application/json
 paths:
@@ -113,8 +114,8 @@ paths:
             The validity of the public key.
           examples:
             application/json: {
-                "valid": true
+              "valid": true
-              }
+            }
           schema:
             type: object
             properties:

api/identity/store_invite.yaml

@@ -18,16 +18,17 @@ info:
 host: localhost:8090
 schemes:
   - https
-  - http
 basePath: /_matrix/identity/api/v1
+consumes:
+  - application/json
 produces:
   - application/json
 paths:
   "/store-invite":
     post:
-      summary: Store pending invitations to a user\'s 3pid.
+      summary: Store pending invitations to a user's 3pid.
       description: |-
-        Store pending invitations to a user\'s 3pid.
+        Store pending invitations to a user's 3pid.
 
         In addition to the request parameters specified below, an arbitrary
         number of other parameters may also be specified. These may be used in
@@ -47,6 +48,8 @@ paths:
 
         Also, the generated ephemeral public key will be listed as valid on
         requests to ``/_matrix/identity/api/v1/pubkey/ephemeral/isvalid``.
+
+        Currently, invites may only be issued for 3pids of the ``email`` medium.
       operationId: storeInvite
       parameters:
         - in: body
@@ -84,7 +87,7 @@ paths:
                 description: The generated token.
               public_keys:
                 type: array
-                description: A list of [server\'s long-term public key, generated ephemeral public key].
+                description: A list of [server's long-term public key, generated ephemeral public key].
                 items:
                   type: string
               display_name:
@@ -111,7 +114,7 @@ paths:
             application/json: {
               "errcode": "M_THREEPID_IN_USE",
               "error": "Binding already known",
-              "mxid": mxid
+              "mxid": "@alice:example.com"
             }
           schema:
             $ref: "../client-server/definitions/errors/error.yaml"