feat(configuration): update docs

docs/features/configuration.rst

@@ -67,7 +67,8 @@ Here is an example Route configuration. You don't need to set all of these thing
       "IPAllowedList": [],
       "IPBlockedList": [],
       "ExcludeAllowedFromBlocked": false
-    }
+    },
+    "Metadata": {}
   }
 
 More information on how to use these options is below.
@@ -345,3 +346,59 @@ Ocelot allows you to choose the HTTP version it will use to make the proxy reque
 """"
 
 .. [#f1] The ``AddOcelot`` method adds default ASP.NET services to DI-container. You could call another more extended ``AddOcelotUsingBuilder`` method while configuring services to build and use custom builder via an ``IMvcCoreBuilder`` interface object. See more instructions in :doc:`../features/dependencyinjection`, "**The AddOcelotUsingBuilder method**" section.
+
+Route Metadata
+--------------
+
+The `Metadata` in the route configuration provides you capabilities to extend Ocelot functionality. The global metadata will be overwritten by the value metadata of a specific role. Here is an example:
+
+.. code-block:: json
+
+    {
+      "Routes": [
+          {
+              "UpstreamHttpMethod": [ "Put", "Delete" ],
+              "UpstreamPathTemplate": "/posts/{postId}",
+              "DownstreamPathTemplate": "/api/posts/{postId}",
+              "DownstreamScheme": "https",
+              "DownstreamHostAndPorts": [
+                  { "Host": "localhost", "Port": 80 }
+              ],
+              "Metadata": {
+                  "api-id": "Posts/UpdateOrDelete",
+                  "my-extension/param1": "overwritten-value",
+                  "other-extension/param1": "value1",
+                  "other-extension/param2": "value2",
+                  "tags": "tag1, tag2, area1, area2, func1"
+              }
+          }
+      ],
+      "GlobalConfiguration": {
+          "Metadata": {
+              "node_name": "data-center-1",
+              "my-extension/param1": "default-value"
+          }
+      }
+    }
+
+Now, you can access route metadata through the `DownstreamRoute` object. For example:
+
+.. code-block:: csharp
+
+    public static class OcelotMiddlewares
+    {
+        public static Task PreAuthenticationMiddleware(HttpContext context, Func<Task> next)
+        {
+            var downstreamRoute = context.Items.DownstreamRoute();
+
+            if(downstreamRoute?.Metadata is {} metadata)
+            {
+                var param1 = metadata.GetValueOrDefault("my-extension/param1") ?? throw new MyExtensionException("Param 1 is null");
+                var param2 = metadata.GetValueOrDefault("my-extension/param2", "custom-value");
+
+                // working with metadata
+            }
+
+            return next();
+        }
+    }