documentation updated

inventory_provider/routes/msr.py

@@ -59,6 +59,11 @@ These endpoints are intended for use by MSR.
 
 .. autofunction:: inventory_provider.routes.msr.bgp_all_peerings
 
+/msr/mdpvn
+--------------------------------------------
+
+.. autofunction:: inventory_provider.routes.msr.mdvpn
+
 /msr/services
 --------------------------------------------
 
@@ -256,6 +261,66 @@ SYSTEM_CORRELATION_SERVICES_LIST_SCHEMA = {
     'minItems': 1  # otherwise the route should return 404
 }
 
+MDVPN_LIST_SCHEMA = {
+    '$schema': 'http://json-schema.org/draft-07/schema#',
+    'definitions': {
+        'mdvpn_group': {
+            'type': 'object',
+            'properties': {
+                'asn': {'type': 'integer'},
+                'AP': {'$ref': '#/definitions/ap_peerings'},
+                'VRR': {'$ref': '#/definitions/vrr_peerings'}
+            },
+            'required': [
+                'asn', 'AP', 'VRR'
+            ],
+            'additionalProperties': False
+        },
+        'ap_peerings': {
+            'type': 'array',
+            'items': {
+                '$ref': '#/definitions/bgplu_peering'
+            }
+        },
+        'bgplu_peering': {
+            'type': 'object',
+            'properties': {
+                'name': {'type': 'string'},
+                'v4': {'type': 'string'},
+                'v6': {'type': 'string'},
+                'hostname': {'type': 'string'}
+            },
+            'required': [
+                'name', 'v4', 'v6', 'hostname'
+            ],
+            'additionalProperties': False
+        },
+        'vrr_peerings': {
+            'type': 'array',
+            'items': {
+                '$ref': '#/definitions/vpn_peering'
+            }
+        },
+        'vpn_peering': {
+            'type': 'object',
+            'properties': {
+                'description': {'type': 'string'},
+                'v4': {'type': 'string'},
+                'hostname': {
+                    'type': 'array',
+                    'items': {
+                        'type': 'string'
+                    },
+                    'minItems': 1
+                }
+            },
+            'additionalProperties': False
+        }
+    },
+    'type': 'array',
+    'items': {'$ref': '#/definitions/mdvpn_group'}
+}
+
 
 @routes.after_request
 def after_request(resp):
@@ -880,6 +945,20 @@ def bgp_all_peerings():
 @routes.route('/mdvpn', methods=['GET', 'POST'])
 @common.require_accepts_json
 def mdvpn():
+    """
+    Handler for `/mdvpn`
+
+    This method returns a list of all BGP-LU peerings, and the VR peerings
+    for both Paris & Ljubljana.
+
+    The response will be formatted according to the following schema:
+
+    .. asjson::
+       inventory_provider.routes.msr.MDVPN_LIST_SCHEMA
+
+    :return:
+    """
+
     def _get_consistent_description(description):
         """
         The same interface in VRR peerings can have multiple names.
@@ -889,6 +968,7 @@ def mdvpn():
         IPv4 address, this serves as a quick and dirty way of merging these
         multiple descriptions into one an external user can use to identify
         the peering reliably.
+
         :param description: The raw description for a VRR peering
         :return: The same description with location prefix removed
         """
@@ -902,7 +982,23 @@ def mdvpn():
                 return description.replace(prefix, '')
         return description
 
+    # !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+    # REVIEW COMMENT ONLY, DO NOT MERGE:
+    # _make_group_index is extremely, extremely generic,
+    # but is it worth extracting, will anything else use it?
+    # !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
     def _make_group_index(group, index_key):
+        """
+        Utility function to take a list and make it a dict based off a given
+        key, for fast lookup of a specific key field.
+
+        :param group: A list of dicts which should all have `index_key` as a
+        field
+        :param index_key: Name of the key to index on
+        :return: Dict with `index_key` as the key field and a list of all
+        matching dicts as the value
+        """
         index = {}
         for peering in group:
             key = peering.get(index_key)