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