Merge pull request #1020 from 3scale/polish-policy-descriptions

Polish descriptions in policy schemas

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

@@ -4,9 +4,9 @@
   "summary": "Caches auths from 3scale backend and batches reports.",
   "description":
     ["This policy caches authorizations from the 3scale backend ",
-     "and also reports in batches. Doing this is more efficient than ",
-     "authorizing and reporting on each request at the expense of losing ",
-     "accuracy in the rate limits."],
+     "and reports them in batches. This is more efficient than authorizing ",
+     "and reporting on each request at the expense of losing accuracy in the ",
+     "rate limits."],
   "version": "builtin",
   "configuration": {
     "type": "object",

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

@@ -2,7 +2,7 @@
   "$schema": "http://apicast.io/policy-v1/schema#manifest#",
   "name": "3scale Referrer",
   "summary": "Sends the 'Referer' to 3scale backend so it can be validated.",
-  "description": "Sends the 'Referer' to 3scale backend so it can be validated",
+  "description": "Sends the 'Referer' to 3scale backend for validation.",
   "version": "builtin",
   "configuration": {
     "type": "object",

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

@@ -4,19 +4,19 @@
   "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 four kinds of caching: \n",
+     "backend. This policy supports four kinds of caching: \n",
      " - Strict: it only caches authorized calls. Denied and failed calls ",
      "invalidate the cache entry.\n",
      " - Resilient: caches authorized and denied calls. Failed calls do not ",
-     "invalidate the cache. This allows us to authorize and deny calls ",
+     "invalidate the cache. This allows APIcast to authorize and deny calls ",
      "according to the result of the last request made even when backend is ",
      "down.\n",
      "- Allow: caches authorized and denied calls. When backend is ",
      "unavailable, it will cache an authorization. In practice, this means ",
      "that when backend is down _any_ request will be authorized unless last ",
      "call to backend for that request returned 'deny' (status code = 4xx). ",
-     "Make sure to understand the implications of that before using this ",
-     "mode. It makes sense only in very specific use cases.\n",
+     "Make sure to understand the implications of this Caching mode before ",
+     "using it. \n",
      "- None: disables caching."],
   "version": "builtin",
   "configuration": {

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

@@ -4,7 +4,7 @@
   "summary": "Executes a policy chain conditionally.",
   "description": [
     "Evaluates a condition, and when it's true, it calls its policy chain. ",
-    "This policy cannot be configured from the 3scale UI."
+    "This policy cannot be configured from the 3scale Admin Portal."
   ],
   "version": "builtin",
   "configuration": {
@@ -60,7 +60,7 @@
       "condition": {
         "$id": "#/definitions/condition",
         "type": "object",
-        "description": "condition to be evaluated",
+        "description": "Condition to be evaluated",
         "properties": {
           "operations": {
             "type": "array",
@@ -82,7 +82,7 @@
         "$ref": "#/definitions/condition"
       },
       "policy_chain": {
-        "description": "the policy chain to execute when the condition is true",
+        "description": "The policy chain to execute when the condition is true",
         "type": "array",
         "items": {
           "type": "object"

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

@@ -3,7 +3,7 @@
   "name": "CORS",
   "summary": "Enables CORS (Cross Origin Resource Sharing) request handling.",
   "description":
-    ["This policy enables CORS (Cross Origin Resource Sharing) request ",
+    ["This policy enables Cross Origin Resource Sharing (CORS) request ",
      "handling. It allows to define CORS headers such as ",
      "Access-Control-Allow-Headers, Access-Control-Allow-Methods, etc. \n",
      "When combined with the APIcast policy, the CORS policy should be ",

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

@@ -3,12 +3,12 @@
   "name": "Anonymous access",
   "summary": "Provides default credentials for unauthenticated requests.",
   "description":
-    ["This policy allows to expose a service without authentication. \n",
+    ["This policy allows service exposure without authentication. \n",
      "It can be useful, for example, for legacy apps that cannot be adapted to ",
      "send the auth params. \n",
      "When the credentials are not provided in the request, this policy ",
      "provides the default ones configured. \n",
-     "An app_id + app_key or a user_key should be configured. \n",
+     "You need to configure a user_key; or, the combination of app_id + app_key. \n",
      "Note: this policy should be placed before the APIcast policy in the chain."],
   "version": "builtin",
   "configuration": {

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

@@ -3,10 +3,10 @@
   "name": "Liquid context debug",
   "summary": "Inspects the available liquid context.",
   "description": [
-    "This is a policy meant only for debugging purposes. This policy ",
+    "This is a policy intended only for debugging purposes. This policy ",
     "returns the context available when evaluating liquid. Any policy can ",
     "modify the context that is shared between policies and that context is ",
-    "available when evaluating liquid. However, documenting what's available ",
+    "available when evaluating liquid. However, documenting what is available ",
     "is not possible because policies can add any arbitrary field. Users who ",
     "want to develop a policy can use this one to know the context available ",
     "in their configuration. ",

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

@@ -105,7 +105,7 @@
       "condition": {
         "$id": "#/definitions/condition",
         "type": "object",
-        "description": "condition to be evaluated",
+        "description": "Condition to be evaluated",
         "properties": {
           "operations": {
             "type": "array",

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

@@ -3,11 +3,11 @@
   "name": "URL rewriting with captures",
   "summary": "Captures arguments in a URL and rewrites the URL using them.",
   "description":
-    ["Captures arguments in a URL and rewrites the URL using those arguments. ",
+    ["Captures arguments in a URL and rewrites the URL using these arguments. ",
      "For example, we can specify a matching rule with arguments like ",
      "'/{orderId}/{accountId}' and a template that specifies how to rewrite ",
-     "the URL using those arguments, for example: ",
-     "'/sales/v2/{orderId}?account={accountId}'. In that case, the request ",
+     "the URL using those arguments. Example: ",
+     "'/sales/v2/{orderId}?account={accountId}'; in this case, the request ",
      "'/123/456' will be transformed into '/sales/v2/123?account=456'"],
   "version": "builtin",
   "configuration": {

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

@@ -122,7 +122,7 @@
     },
     "properties": {
       "rules": {
-        "description": "list of rules to be applied",
+        "description": "List of rules to be applied",
         "type": "array",
         "items": {
           "type": "object",

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

@@ -13,17 +13,17 @@
     "type": "object",
     "properties": {
       "rules": {
-        "description": "list of rules to be applied",
+        "description": "List of rules to be applied",
         "type": "array",
         "items": {
           "type": "object",
           "properties": {
             "regex": {
-              "description": "regular expression to be matched",
+              "description": "Regular expression to be matched",
               "type": "string"
             },
             "url": {
-              "description": "new URL in case of match",
+              "description": "New URL in case of match",
               "type": "string"
             }
           },