refactor: update descriptions and provide more detail for handling Ma…

…ilFolders

refs conjoon/php-lib-conjoon#28

descriptions/rest-api-email-0/rest-api-email-0.json

@@ -59,6 +59,9 @@
               }
             }
           },
+          "400": {
+            "$ref": "#/components/responses/400-BadRequest"
+          },
           "401": {
             "$ref": "#/components/responses/401-Unauthorized"
           }
@@ -70,8 +73,8 @@
         "tags": [
           "MailFolders"
         ],
-        "summary": "Lists mail boxes",
-        "description": "Returns a list of available mail boxes for the client and the `MailAccount`. \n\n#### Mailbox Subscriptions\nMailboxes the client has subscribed to can be passed using the `filter`-query param. \n_Example:_\nThe client has subscribed to the mailboxes with the id `INBOX` and `[Gmail]`:\n\n```http\nGET MailAccounts/googlemail/MailFolders?filter={\"AND\":[{\"IN\":{\"id\":[\"INBOX\",\"[Gmail]\"]}}]} HTTP 1/1\n```",
+        "summary": "Lists mail folders",
+        "description": "Returns a list of available mail folders for the client and the `MailAccount`. \n\n### Mailbox Subscriptions\nMailboxes the client is interested in can be specified using the `filter`-query param. \n_Example:_\nThe client has subscribed to the mail folders with the id `INBOX` and `Personal Mail`:\n\n```http\nGET MailAccounts/googlemail/MailFolders?filter={\"IN\":{\"id\":[\"INBOX\",\"Personal Mail\"]}} HTTP 1/1\n```\n\nIf this filter is omitted, the server **MUST** respond with all mailboxes available for the specified `MailAccount`. \n\n## `options`\nThe client **MAY** send an `options`-query parameter providing various processing informations with the request.\n\nThe server **SHOULD** be able to process the following options send by the client:\n\n#### `options[MailFolder][dissolveNamespaces]`\n - _Type_: `String[]`\n A list of namespaces that should get dissolved by the server, affecting all mailboxes available with the specified\n `MailAccount`. If this option is provided, the server **SHOULD**\n ignore the specified namespaces when assembling a hierarchical tree structure of the mailboxes.\n\n##### Example\n\nGiven the following mailbox hierarchy\n\n ```\nINBOX\nINBOX.Drafts\nINBOX.Drafts.Revision\nINBOX.Drafts.Revision.TlDr\nINBOX.Drafts.Revision.SkipMe\nINBOX.Drafts.Revision.TlNs\nINBOX.Sent\n ```\n\nWhen setting `options[MailFolder][dissolveNamespaces]` to `[\"INBOX\"]`\n\n```http\nGET MailAccounts/googlemail/MailFolders?options[MailFolder]={\"dissolveNamespaces\": [\"INBOX\"]} HTTP 1/1\n```\n\nthe server **SHOULD** treat the assembling\nof the tree structure as if mailboxes were available\n in the following form:\n\n```\nINBOX\nDrafts\nDrafts.Revision\nDrafts.Revision.TlDr\nDrafts.Revision.SkipMe\nDrafts.Revision.TlNs\nSent\n```\n\nwhile providing the associated mailbox-ids as it, i.e., for the `MailFolder` `Drafts`, its id is still `INBOX.drafts`.\n\n##### `INBOX` treatment:\nThe `INBOX`-mailbox **SHOULD** serve as the root folder for incoming messages; as such, \nit is recommended to leave this namespace as is, except for the mailboxes that are direct\nsuccessors of this namepace.\n\nIf multiple equal mailbox names appear in one and the same level of a resulting tree stucture, it is up to the \nimplementing server to take action so the client can still distinguish between the mailboxes.",
         "operationId": "getMailFolders",
         "parameters": [
           {
@@ -84,6 +87,14 @@
             "in": "query",
             "name": "filter",
             "description": "filter param for additional filter information"
+          },
+          {
+            "schema": {
+              "type": "string"
+            },
+            "in": "query",
+            "name": "options",
+            "description": "A query parameter group providing additional processing information."
           }
         ],
         "responses": {
@@ -106,6 +117,9 @@
               }
             }
           },
+          "400": {
+            "$ref": "#/components/responses/400-BadRequest"
+          },
           "401": {
             "$ref": "#/components/responses/401-Unauthorized"
           },
@@ -2089,7 +2103,7 @@
       "MessageBody_ResourceIdentifier": {
         "title": "MessageBody_ResourceIdentifier",
         "x-stoplight": {
-          "id": "i0279o78op8lw"
+          "id": "x105b7zzcm8b4"
         },
         "type": "object",
         "description": "Resource Identifier for a `MessageBody`.",
@@ -2106,7 +2120,7 @@
       "MessageBody_ResourceLinkage": {
         "title": "MessageBody_ResourceLinkage",
         "x-stoplight": {
-          "id": "6ohwpshud47fp"
+          "id": "g9mb1r1pbvrzh"
         },
         "type": "object",
         "description": "Resource Linkage for a `MessageBody`.",
@@ -2248,7 +2262,7 @@
       "MailFolder_ResourceLinkage": {
         "title": "MailFolder_ResourceLinkage",
         "x-stoplight": {
-          "id": "6ohwpshud47fp"
+          "id": "opv0l0316cemv"
         },
         "type": "object",
         "properties": {
@@ -2261,7 +2275,7 @@
       "MailAccount_ResourceLinkage": {
         "title": "MailAccount_ResourceLinkage",
         "x-stoplight": {
-          "id": "3lar9glo8fii5"
+          "id": "2257ypw8q6l2d"
         },
         "type": "object",
         "description": "Resource Linkage for a `MailAccount`.",
@@ -2346,7 +2360,7 @@
       "ProblemObject": {
         "title": "Problem Object",
         "x-stoplight": {
-          "id": "tshdi3r02p0cj"
+          "id": "eoqvj699w8dph"
         },
         "type": "object",
         "description": "Problem Object representatives according to [rfc7807](https://datatracker.ietf.org/doc/html/rfc7807). The Problem representative is being available in the structure of an Error Object according to the [JSON:API's Error Object specifications](https://jsonapi.org/format/#errors).\n\n\n## Available fields\n\n### `status`\n - Type : `int`\n \nThe HTTP status code ([RFC7231], Section 6) generated by the origin server for this occurrence of the problem.\n \n ### `title`\n -  Type: `string`\n \nA short, human-readable summary of the problem type.  It SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization (e.g., using proactive content negotiation; see [RFC7231], Section 3.4)\n \n ### `detail`\n - Type: `string`\n \n A human-readable explanation specific to this occurrence of the problem.\n\n### `meta`\n - Type: `object`\n\n`meta` is an object that may contain the field `instance`, a URI reference that identifies the specific occurrence of the problem.  It may or may not yield further information if dereferenced.\n\n### `links`\n - Type: `object`\n\n`links` is an object that may contain the field `about`, a URI reference [RFC3986] that identifies the problem type.  This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML [W3C.REC-html5-20141028]).  When this member is not present, its value is assumed to be \"about:blank\".",
@@ -2382,7 +2396,7 @@
       "ErrorObject": {
         "title": "Error Object",
         "x-stoplight": {
-          "id": "8sfbzi93abura"
+          "id": "uk2kd5co6f66r"
         },
         "type": "object",
         "description": "## Available fields\nThe response contains [`Problems`](https://datatracker.ietf.org/doc/html/rfc7807) transformed to [`Error Objects`](https://jsonapi.org/format/#errors) according to [JSON:API](https://jsonapi.org) specifications. Each object provides additional information about problems encountered while performing an operation. \n\n### `errors`\n\n- Type: `array`\n\nThe errors object contains one error object or a list of errors that where encountered during the operation, whereas the first entry should be the most recently encountered error during the operation, and the last entry should be the least recently encountered error.",