[data views] Swap references API docs (elastic#175183)

## Summary

Docs for the swap references api -
elastic#163225

The docs are on the terse side - I think this makes sense since this is
a tool that should be used infrequently and only by people who use saved
object references.

---------

Co-authored-by: amyjtechwriter <[email protected]>
Co-authored-by: Davis McPhee <[email protected]>

docs/api/data-views.asciidoc

@@ -16,6 +16,8 @@ The following data views APIs are available:
     ** <<data-views-api-create, Create data view API>> to create data view
     ** <<data-views-api-update, Update data view API>> to partially updated data view
     ** <<data-views-api-delete, Delete data view API>> to delete a data view
+    ** <<data-views-api-swap-references-preview, Data view swap references preview API>> to preview a data view reference swap
+    ** <<data-views-api-swap-references, Data view swap references API>> to perform a data view reference swap
 * Default data views
     ** <<data-views-api-default-get, Get default data view API>> to retrieve a default data view
     ** <<data-views-api-default-set, Set default data view API>> to set a default data view
@@ -33,6 +35,8 @@ include::data-views/get.asciidoc[]
 include::data-views/create.asciidoc[]
 include::data-views/update.asciidoc[]
 include::data-views/delete.asciidoc[]
+include::data-views/swap_references_preview.asciidoc[]
+include::data-views/swap_references.asciidoc[]
 include::data-views/default-get.asciidoc[]
 include::data-views/default-set.asciidoc[]
 include::data-views/update-fields.asciidoc[]

docs/api/data-views/swap_references.asciidoc

@@ -0,0 +1,84 @@
+[[data-views-api-swap-references]]
+=== Swap references data view API
+++++
+<titleabbrev>Swap references</titleabbrev>
+++++
+
+Swap saved object references
+
+[WARNING]
+====
+Misuse can break large numbers of saved objects! Practicing with a backup is recommended. 
+====
+
+[NOTE]
+====
+For the most up-to-date API details, refer to the
+{kib-repo}/tree/{branch}/src/plugins/data_views/docs/openapi[open API specification].
+====
+
+[[data-views-api-swap-references-request]]
+==== Request
+
+`POST <kibana host>:<port>/api/data_views/swap_references`
+
+`POST <kibana host>:<port>/s/<space_id>/api/data_views/swap_references`
+
+
+[[data-views-api-swap-references-request-body]]
+==== Request body
+
+`fromId`::
+(Required, string) Saved object reference to change.
+
+`toId`::
+(Required, string) New saved object reference value to replace the old.
+
+`delete`::
+ (Optional, boolean) Deletes referenced saved object if all references are removed.
+
+`fromType`::
+ (Optional, string) Specify the type of the saved object reference to alter. Default is `index-pattern` for data view.
+
+`forId`::
+(Optional, string or string[]) Limit the affected saved objects to one or more by IDs.
+
+`forType`::
+ (Optional, string) Limit the affected saved objects by type.
+
+[[data-views-api-swap-references-errors-codes]]
+==== Response code
+
+`200`::
+Indicates a successful call.
+
+[[data-views-api-swap-references-example]]
+==== Examples
+
+Swap references to data view id "abcd-efg" with "xyz-123":
+
+[source,sh]
+--------------------------------------------------
+$ curl -X api/data_views/swap_references
+{
+     "fromId" : "abcd-efg",
+     "toId" : "xyz-123",
+     "delete" : true // optional, removes data view which is no longer referenced
+}
+
+--------------------------------------------------
+// KIBANA
+
+The API returns a list of affected saved objects:
+
+[source,sh]
+--------------------------------------------------
+{
+  result: [{ id: "123", type: "visualization" }],
+  deleteStatus: {
+    remainingRefs: 0,
+    deletePerformed: true
+  }
+}
+--------------------------------------------------
+

docs/api/data-views/swap_references_preview.asciidoc

@@ -0,0 +1,74 @@
+[[data-views-api-swap-references-preview]]
+=== Swap references preview data view API
+++++
+<titleabbrev>Swap references preview</titleabbrev>
+++++
+
+Swap saved object references preview
+
+[NOTE]
+====
+For the most up-to-date API details, refer to the
+{kib-repo}/tree/{branch}/src/plugins/data_views/docs/openapi[open API specification].
+====
+
+[[data-views-api-swap-references-preview-request]]
+==== Request
+
+`POST <kibana host>:<port>/api/data_views/swap_references/_preview`
+
+`POST <kibana host>:<port>/s/<space_id>/api/data_views/swap_references/_preview`
+
+
+[[data-views-api-swap-references-preview-request-body]]
+==== Request body
+
+`fromId`::
+(Required, string) Saved object reference to change.
+
+`toId`::
+(Required, string) New saved object reference value to replace the old.
+
+`delete`::
+ (Optional, boolean) Deletes referenced saved object if all references are removed.
+
+`fromType`::
+ (Optional, string) Specify the type of the saved object reference to alter. Default is `index-pattern` for data view.
+
+`forId`::
+(Optional, string or string[]) Limit the affected saved objects to one or more by IDs.
+
+`forType`::
+ (Optional, string) Limit the affected saved objects by type.
+
+[[data-views-api-swap-references-preview-errors-codes]]
+==== Response code
+
+`200`::
+Indicates a successful call.
+
+[[data-views-api-swap-references-preview-example]]
+==== Examples
+
+Preview swapping references to data view id "abcd-efg" with "xyz-123":
+
+[source,sh]
+--------------------------------------------------
+$ curl -X api/data_views/swap_references/_preview
+{
+     "fromId" : "abcd-efg",
+     "toId" : "xyz-123"
+}
+
+--------------------------------------------------
+// KIBANA
+
+The API returns a list of affected saved objects:
+
+[source,sh]
+--------------------------------------------------
+{
+  result: [{ id: "123", type: "visualization" }],
+}
+--------------------------------------------------
+