policy/manifests: include summaries

Also, expand a bit descriptions that were as short as a summary.

gateway/src/apicast/policy/apicast/apicast-policy.json

@@ -1,7 +1,11 @@
 {
   "$schema": "http://apicast.io/policy-v1/schema#manifest#",
   "name": "APIcast",
-  "description": "Main functionality of APIcast.",
+  "summary": "Main functionality of APIcast to work with the 3scale API manager.",
+  "description":
+    ["Main functionality of APIcast to work with the 3scale API ",
+     "manager. This includes matching of mapping rules, authorization, ",
+     "reporting, etc."],
   "version": "builtin",
   "configuration": {
     "type": "object",

gateway/src/apicast/policy/caching/apicast-policy.json

@@ -1,6 +1,7 @@
 {
   "$schema": "http://apicast.io/policy-v1/schema#manifest#",
   "name": "Caching",
+  "summary": "Controls how to cache authorizations returned by the 3scale backend.",
   "description":
     ["Configures a cache for the authentication calls against the 3scale ",
      "backend. This policy support three kinds of caching: \n",

gateway/src/apicast/policy/cors/apicast-policy.json

@@ -1,7 +1,11 @@
 {
   "$schema": "http://apicast.io/policy-v1/schema#manifest#",
   "name": "CORS",
-  "description": "This policy enables CORS (Cross Origin Resource Sharing) request handling.",
+  "summary": "Enables CORS (Cross Origin Resource Sharing) request handling.",
+  "description":
+    ["This policy enables CORS (Cross Origin Resource Sharing) request ",
+     "handling. It allows to define CORS headers such as ",
+     "Access-Control-Allow-Headers, Access-Control-Allow-Methods, etc."],
   "version": "builtin",
   "configuration": {
     "type": "object",

gateway/src/apicast/policy/echo/apicast-policy.json

@@ -1,6 +1,7 @@
 {
   "$schema": "http://apicast.io/policy-v1/schema#manifest#",
   "name": "Echo",
+  "summary": "Prints the request back to the client and optionally sets a status code.",
   "description":
     ["This policy prints the request back to the client and optionally sets ",
      "a status code."],

gateway/src/apicast/policy/headers/apicast-policy.json

@@ -1,6 +1,7 @@
 {
   "$schema": "http://apicast.io/policy-v1/schema#manifest#",
   "name": "Headers",
+  "summary": "Allows to include custom headers.",
   "description":
     ["This policy allows to include custom headers that will be sent to the ",
      "upstream as well as modify or delete the ones included in the original ",

gateway/src/apicast/policy/soap/apicast-policy.json

@@ -1,6 +1,7 @@
 {
   "$schema": "http://apicast.io/policy-v1/schema#manifest#",
   "name": "SOAP",
+  "summary": "Adds support for a small subset of SOAP.",
   "description":
   ["This policy adds support for a very small subset of SOAP. \n",
    "It expects a SOAP action URI in the SOAPAction header or the Content-Type ",

gateway/src/apicast/policy/upstream/apicast-policy.json

@@ -1,7 +1,11 @@
 {
   "$schema": "http://apicast.io/policy-v1/schema#manifest#",
   "name": "Upstream",
-  "description": "This policy allows to modify the host of a request based on its path.",
+  "summary": "Allows to modify the host of a request based on its path.",
+  "description":
+    ["This policy allows to modify the host of a request based on its path. ",
+     "It accepts regular expressions that, when matched against the path, ",
+     "replace it with a given string."],
   "version": "builtin",
   "configuration": {
     "type": "object",

gateway/src/apicast/policy/url_rewriting/apicast-policy.json

@@ -1,6 +1,7 @@
 {
   "$schema": "http://apicast.io/policy-v1/schema#manifest#",
   "name": "URL rewriting",
+  "summary": "Allows to modify the path of a request.",
   "description":
     ["This policy allows to modify the path of a request. ",
      "The operations supported are sub and gsub based on ngx.re.sub and ",