edit doc entries for sharing routes with spaces

Co-authored-by: Merric de Launey <[email protected]>
Co-authored-by: David Alvarado <[email protected]>

docs/v3/source/includes/resources/routes/_list_shared_routes.md.erb

@@ -0,0 +1,47 @@
+### Lists shared spaces relationship (experimental)
+
+Lists the spaces that the route has been shared to.
+
+```
+Example Request
+```
+
+```shell
+curl "https://api.example.org/v3/routes/[guid]/relationships/shared_spaces" \
+  -H "Authorization: bearer [token]" \
+  -H "Content-type: application/json"
+```
+
+```http
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+  "data": [
+    { "guid": "space-one-guid" },
+    { "guid": "space-two-guid" }
+  ],
+  "links": {
+    "self": {
+      "href":"http://api.example.com/v3/routes/[guid]/relationships/shared_spaces"
+    }
+  }
+}
+```
+
+#### Definition
+`GET /v3/routes/:guid/relationships/shared_spaces`
+
+#### Permitted roles
+
+ |
+--- |
+Admin |
+Admin Read-Only |
+Global Auditor |
+Org Auditor |
+Org Manager |
+Space Auditor |
+Space Developer |
+Space Manager |
+Space Supporter |

docs/v3/source/includes/resources/routes/_share_routes.md.erb

@@ -0,0 +1,55 @@
+### Share a route with other spaces (experimental)
+
+This endpoint shares the route with the specified spaces. In order to share into a space the requesting user must have write permission in the target space.
+
+```
+Example Request
+```
+
+```shell
+curl "https://api.example.org/v3/routes/[guid]/relationships/shared_spaces" \
+  -X POST \
+  -H "Authorization: bearer [token]" \
+  -H "Content-type: application/json" \
+  -d '{
+    "data": [
+      { "guid": "space-one-guid" },
+      { "guid": "space-two-guid" }
+    ]
+  }'
+```
+
+```http
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+  "data": [
+    { "guid": "space-one-guid" },
+    { "guid": "space-two-guid" }
+  ],
+  "links": {
+    "self": {
+      "href":"http://api.example.com/v3/routes/[guid]/relationships/shared_spaces"
+    }
+  }
+}
+```
+
+#### Definition
+`POST /v3/routes/:guid/relationships/shared_spaces`
+
+#### Required parameters
+
+Name | Type | Description
+---- | ---- | -----------
+**data** | [_to-many relationship_](#to-many-relationships) | Shared space relationships; each space will have this route shared to it
+
+#### Permitted roles
+
+ |
+--- |
+Admin |
+Space Developer |
+Space Supporter |
+

docs/v3/source/includes/resources/routes/_unshare_routes.md.erb

@@ -0,0 +1,31 @@
+### Unshare a route that was shared with another space (experimental)
+
+Unshares a route that was shared with another space.
+
+```
+Example Request
+```
+
+```shell
+curl "https://api.example.org/v3/routes/:guid/relationships/shared_spaces/[space_guid]" \
+  -X DELETE \
+  -H "Authorization: bearer [token]" \
+  -H "Content-type: application/json"
+```
+
+```http
+HTTP/1.1 204 No Content
+```
+
+#### Definition
+`DELETE /v3/routes/:guid/relationships/shared_spaces/:space_guid`
+
+#### Permitted roles
+
+ |
+--- |
+Admin |
+Space Developer |
+Space Supporter |
+
+

docs/v3/source/index.html.md

@@ -247,6 +247,9 @@ includes:
   - resources/routes/update
   - resources/routes/delete
   - resources/routes/check_route_reservations
+  - resources/routes/list_shared_routes
+  - resources/routes/share_routes
+  - resources/routes/unshare_routes
   - resources/routes/list_destinations
   - resources/routes/insert_destinations
   - resources/routes/replace_destinations