Rephrased headers of all endpoints to improve consistency (#202)

* Rephrased headers of all endpoints to improve consistency

* Added a link also on the top header

Author: glpatcern

IETF-RFC.md

@@ -309,7 +309,7 @@ itself be an object containing the following fields:
 * OPTIONAL: inviteAcceptDialog (string) - URL path of a web page where a user can accept an invite, when query parameters `"token"` and `"providerDomain"` are provided. Implementations that offer the `"invites"` capability SHOULD provide this URL as well in order to enhance the UX of the Invite Flow. If for example `"/index.php/apps/sciencemesh/accept"` is specified here then a WAYF Page SHOULD redirect the end-user to `/index.php/apps/sciencemesh/accept?token=zi5kooKu3ivohr9a&providerDomain=example.com`.
 
 # Share Creation Notification
-To create a share, the sending server SHOULD make a HTTP POST request
+To create a Share, the Sending Server SHOULD make a HTTP POST request
 
 * to the `/shares` path in the Receiving Server's OCM API
 * using `application/json` as the `Content-Type` HTTP request header
@@ -488,6 +488,10 @@ make a HTTP POST request
 * OPTIONAL resourceType (string) - copied from the Share Creation Notification for the Share this notification is about
 * OPTIONAL notification (object) - optional additional parameters, depending on the notification and the resource type
 
+For example, a notification MAY be sent by a recipient to let the provider know that the recipient declined a share. In this case, the provider site MAY mark the share as declined for its user(s).
+Similarly, it MAY be sent by a provider to let the recipient know that the provider removed a given share, such that the recipient MAY clean it up from its database.
+A notification MAY also be sent to let a recipient know that the provider removed that recipient from the list of trusted users, along with any related share. The recipient MAY reciprocally remove that provider from the list of trusted users, along with any related share.
+
 
 ### Receiving Party Notification
 If the Share Creation Notification is not discarded by the Receiving Server, they MAY notify the Receiving Party passively by adding the Share to some inbox list, and MAY also notify them actively through for instance a push notification or an email message.

spec.yaml

@@ -1,7 +1,10 @@
 openapi: 3.0.3
 info:
   title: Open Cloud Mesh API
-  description: Open Cloud Mesh Open API Specification.
+  description: >
+    Open Cloud Mesh OpenAPI Specification.
+    The semantic of the Protocol Specification is detailed in the
+    [IETF-RFC.md](https://github.com/cs3org/OCM-API/blob/develop/IETF-RFC.md) document.
   version: 1.2.0
   x-logo:
     url: logo.png
@@ -32,8 +35,8 @@ paths:
     get:
       summary: Legacy discovery endpoint
       description: >
-        This endpoint is a replica of `/.well-known/ocm`, and MUST be
-        served at the OCM Server's root FQDN as well.
+        This endpoint is a replica of `/.well-known/ocm`, and MUST be served
+        at the OCM Server's root FQDN as well to ensure backwards compatibility.
         OCM Servers MUST support both.
       responses:
         "200":
@@ -44,11 +47,11 @@ paths:
                 $ref: "#/components/schemas/Discovery"
   /shares:
     post:
-      summary: Create a new share
+      summary: Share Creation Notification endpoint
       description: >
-        After the provider created a local share, it sends a `share` object to
-        the consumer containing the  information which is needed to start
-        synchronization between the two services.
+        This endpoint is used by a Sending Server to notify a Receiving Server that
+        a new Share has been created. See [Share Creation Notification](https://github.com/cs3org/OCM-API/blob/develop/IETF-RFC.md#share-creation-notification)
+        for more details.
       requestBody:
         content:
           application/json:
@@ -117,21 +120,12 @@ paths:
                 $ref: "#/components/schemas/Error"
   /notifications:
     post:
-      summary: Send a notification to a remote party about a previously known entity
+      summary: Share Acceptance Notification endpoint
       description: >
-        Notifications are optional messages. They are expected to be used to
-        inform the
-        other party about a change about a previously known entity, such as a share or
-        a trusted user.
-        For example, a notification MAY be sent by a recipient to let the provider know
-        that the recipient declined a share. In this case, the provider site MAY mark the
-        share as declined for its user(s).
-        Similarly, it MAY be sent by a provider to let the recipient know that the provider
-        removed a given share, such that the recipient MAY clean it up from its database.
-        A notification MAY also be sent to let a recipient know that the provider
-        removed that recipient from the list of trusted users, along with any related share.
-        The recipient MAY reciprocally remove that provider from the list of trusted users,
-        along with any related share.
+        This optional endpoint is used to inform the other party about a change
+        that concerns a previously known entity, such as a Share or a trusted User.
+        See [Share Acceptance Notification](https://github.com/cs3org/OCM-API/blob/develop/IETF-RFC.md#share-acceptance-notification)
+        for more details.
       requestBody:
         content:
           application/json:
@@ -193,11 +187,10 @@ paths:
                 $ref: "#/components/schemas/Error"
   /invite-accepted:
     post:
-      summary: |
-        Inform the sender that an invitation was accepted to start sharing.
+      summary: Invitation Acceptance endpoint
       description: >
-        See the Open Cloud Mesh [Invite flow
-        spec](https://github.com/cs3org/OCM-API/blob/develop/IETF-RFC.md#invite-flow)
+        This optional endpoint is used to inform the Sender that an Invitation was accepted.
+        See [Invite flow](https://github.com/cs3org/OCM-API/blob/develop/IETF-RFC.md#invite-flow)
         for more details.
       requestBody:
         content:
@@ -240,10 +233,11 @@ paths:
                 $ref: "#/components/schemas/Error"
   /token:
     post:
-      summary: Obtain a (potentially short-lived) bearer token in exchange for a code
+      summary: Token Exchange endpoint
       description: >
-        See
-        https://github.com/cs3org/OCM-API/blob/develop/IETF-RFC.md#resource-access
+        This optional endpoint allows to obtain a (potentially short-lived) bearer token in exchange for a code.
+        See [Resource Access](https://github.com/cs3org/OCM-API/blob/develop/IETF-RFC.md#resource-access)
+        for more details.
       requestBody:
         content:
           application/json: