ocm: enhance invitation flow

spec.yaml

@@ -355,42 +355,47 @@ paths:
               type: string
           schema:
             $ref: "#/definitions/Error"
-  /invite/accept:
+  invite/forward:
     post:
-      summary: Accept an invite to a shared document
-      description: Foo
+      summary: Forward an invitation to start sharing
+      description: Sends an invitation to an end-user (by mail for example)
       parameters:
         - name: invite
           in: body
-          description: The JSON object to notify OCM that an invite has been accepted.
+          description: The JSON object representing an invitation to send to an end-user.
           required: true
           schema:
-            $ref: "#/definitions/AcceptInvite"
+            $ref: "#/definitions/Invite"
       responses:
         200:
-          description: Auth ok!
+          description: Invitation sent.
         400:
-          description: Invalid token?
+          description: |
+            Bad request due to invalid parameters, e.g. email is not valid.
           schema:
-            $ref: "#/definitions/Error" 
-  invite/forward:
+            $ref: "#/definitions/400"            
+  /invite/accept:
     post:
-      summary: Forward information from invite to the cloud provider.
-      description: Foo
+      summary: Accept an invititation to start sharing.
+      description: Accepts an invitation to the shared document so the provider can initiate the OCM share creation.
       parameters:
         - name: invite
           in: body
-          description: The JSON object to send to the cloud provider with the invitaiton information.
+          description: The JSON object to notify the OCM provider that an invite has been accepted.
           required: true
           schema:
-            $ref: "#/definitions/Invite"
+            $ref: "#/definitions/AcceptInvite"
       responses:
         200:
-          description: Ok!
+          description: Invitation accepted.
         400:
-          description: Invalid token?
+          description: The invitation token is invalid.
           schema:
             $ref: "#/definitions/Error" 
+        403:
+          description: Remote service is not trusted to accept invitations.
+          schema:
+            $ref: "#/definitions/Error"
 definitions:
   400:
     type: object
@@ -547,30 +552,33 @@ definitions:
     allOf:
       - properties:
           userId:
-            type: string # probably uuid?
-            description: Unique ID to identify the person accepting the invite.
+            type: string
+            description: Unique ID to identify the user at the remote provider accepting the invite.
             example: 9303
           provider:
-            type: string # probably uuid?
-            description: Id to identify the provider
-            example: abc
+            type: string 
+            format: url
+            description: URL of the receiver OCM service.
+            example: https://receiver.org/ocm
           token:
-            type: string # probably some other kind of token
+            type: string
             description: Token received in the invite
-            example: abc-123
+            example: xyz
           senderProvider: 
-            type: string # probably uuid?
-            description: Id to identify the provider of the sender
-            example: ddd
+            type: string 
+            format: url
+            description: URL of the OCM sender service.
+            example: https://sender.org/ocm/
   Invite:
     type: object
     allOf:
       - properties:
           token:
-            type: string # probably some other kind of token
-            description: Token received in the invite
-            example: abc-123
+            type: string
+            description: Token generated by the service sending the invitation.
+            example: xyz
           senderProvider: 
-            type: string # probably uuid?
-            description: Id to identify the provider of the sender
-            example: ddd
+            type: string 
+            format: url
+            description: URL of the OCM sender service.
+            example: https://sender.org/ocm/