Merge pull request #675 from 3scale/clarify-order-in-schema-descriptions

[THREESCALE-799] policy: document in schemas when the order in the chain matters

CHANGELOG.md

@@ -9,6 +9,8 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 ### Added
 
 - Rate Limit policy [PR #648](https://github.com/3scale/apicast/pull/648)
+- [THREESCALE-799](https://issues.jboss.org/browse/THREESCALE-799) Documented restrictions in the position in the chain for some policies [PR #675](https://github.com/3scale/apicast/pull/675)
+
 ### Changed
 
 - descriptions in `oneOf`s in policy manifests have been replaced with titles [PR #663](https://github.com/3scale/apicast/pull/663)

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

@@ -5,7 +5,9 @@
   "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."],
+     "Access-Control-Allow-Headers, Access-Control-Allow-Methods, etc. \n",
+     "When combined with the APIcast policy, the CORS policy should be ",
+     "placed before it in the chain."],
   "version": "builtin",
   "configuration": {
     "type": "object",

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

@@ -5,7 +5,9 @@
   "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."],
+     "replace it with a given string. \n",
+     "When combined with the APIcast policy, the upstream policy should be ",
+     "placed before it in the policy chain"],
   "version": "builtin",
   "configuration": {
     "type": "object",

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

@@ -7,7 +7,11 @@
      "The operations supported are sub and gsub based on ngx.re.sub and ",
      "ngx.re.gsub provided by OpenResty. Please check ",
      "https://github.com/openresty/lua-nginx-module for more details on how ",
-     "to define regular expressions and learn the options supported."],
+     "to define regular expressions and learn the options supported. \n",
+     "When combined with the APIcast policy, if the URL rewriting policy is ",
+     "placed before it in the chain, the APIcast mapping rules will apply to the ",
+     "modified path. If the URL rewriting policy is placed after APIcast in the ",
+     "chain, then the mapping rules will apply to the original path."],
   "version": "builtin",
   "configuration": {
     "type": "object",