finish routes api ref

Our API ref for 'routes' was missing some sample route objects in
request/response JSON samples, as well as documenting the fact that
routes can be updated with PUT requests on routers.

Change-Id: I50f6d8193163586ab6f4f3bf61830fc9407ff7a2
Closes-Bug: #1564887

api-ref/source/v2/routers.inc

@@ -10,6 +10,13 @@ appropriate external gateway.
 
 This resource is provided when ``router`` extension is enabled.
 
+Extra routes extension (``extraroute``)
+=======================================
+
+The extra route extension (``extraroute``) extends ``router`` resources adding
+a ``routes`` attribute that contains an array of route objects. Each route
+object has a ``destination`` and ``nexthop`` attribute representing the route.
+
 List routers
 ============
 
@@ -233,6 +240,7 @@ Request
    - external_fixed_ips: router-external_fixed_ips
    - router_id: router_id
    - description: description-request
+   - routes: router-routes-request
 
 Request Example
 ---------------

api-ref/source/v2/samples/routers/router-show-response.json

@@ -25,7 +25,12 @@
         "id": "f8a44de0-fc8e-45df-93c7-f79bf3b01c95",
         "name": "router1",
         "revision_number": 1,
-        "routes": [],
+        "routes": [
+            {
+                "destination": "179.24.1.0/24",
+                "nexthop": "172.24.3.99"
+            }
+        ],
         "status": "ACTIVE",
         "project_id": "0bd18306d801447bb457a46252d82d13",
         "tenant_id": "0bd18306d801447bb457a46252d82d13"

api-ref/source/v2/samples/routers/router-update-request.json

@@ -8,6 +8,12 @@
                     "ip_address": "172.24.4.6",
                     "subnet_id": "b930d7f6-ceb7-40a0-8b81-a425dd994ccf"
                 }
+            ],
+            "routes": [
+                {
+                    "destination": "179.24.1.0/24",
+                    "nexthop": "172.24.3.99"
+                }
             ]
         }
     }

api-ref/source/v2/samples/routers/router-update-response.json

@@ -21,7 +21,12 @@
         "id": "f8a44de0-fc8e-45df-93c7-f79bf3b01c95",
         "name": "router1",
         "revision_number": 3,
-        "routes": [],
+        "routes": [
+            {
+                "destination": "179.24.1.0/24",
+                "nexthop": "172.24.3.99"
+            }
+        ],
         "status": "ACTIVE",
         "project_id": "0bd18306d801447bb457a46252d82d13",
         "tenant_id": "0bd18306d801447bb457a46252d82d13"

api-ref/source/v2/samples/routers/routers-list-response.json

@@ -26,7 +26,12 @@
             "id": "915a14a6-867b-4af7-83d1-70efceb146f9",
             "name": "router2",
             "revision_number": 1,
-            "routes": [],
+            "routes": [
+                {
+                    "destination": "179.24.1.0/24",
+                    "nexthop": "172.24.3.99"
+                }
+            ],
             "status": "ACTIVE",
             "project_id": "0bd18306d801447bb457a46252d82d13",
             "tenant_id": "0bd18306d801447bb457a46252d82d13"