api: Address issues with remote consoles APIs

* Add a note explaining presence of xvpvnc console type
* Make 'url' mandatory in create response
* Remove unnecessary description fields: we will populate these later
* De-deuplcate request body schemas
* Re-add references to the rdp console to the api-ref

Change-Id: I5555b8cf7a83fad689e98522850b5550b49566ed
Signed-off-by: Stephen Finucane <stephenfin@redhat.com>

api-ref/source/parameters.yaml

@@ -5986,17 +5986,20 @@ remote_console:
 remote_console_protocol:
   description: |
     The protocol of remote console. The valid values are ``vnc``, ``spice``,
-    ``serial`` and ``mks``. The protocol ``mks`` is added since Microversion
-    ``2.8``.
+    ``rdp``, ``serial`` and ``mks``. The protocol ``mks`` is added since
+    Microversion ``2.8``. The protocol ``rdp`` requires the Hyper-V driver
+    which was removed in the 29.0.0 (Caracal) release.
   in: body
   required: true
   type: string
 remote_console_type:
   description: |
     The type of remote console. The valid values are ``novnc``,
-    ``spice-html5``, ``spice-direct``, ``serial``, and ``webmks``. The type
-    ``webmks`` was added in Microversion ``2.8``, and the type
-    ``spice-direct`` was added in Microversion ``2.99``.
+    ``rdp-html5``, ``spice-html5``, ``spice-direct``, ``serial``, and
+    ``webmks``. The type ``webmks`` was added in Microversion ``2.8`` and the
+    type ``spice-direct`` was added in Microversion ``2.99``. The type
+    ``rdp-html5`` requires the Hyper-V driver which was removed in the 29.0.0
+    (Caracal) release.
   in: body
   required: true
   type: string

api-ref/source/servers-actions.inc

@@ -8,20 +8,22 @@
 Enables all users to perform an action on a server. Specify the action
 in the request body.
 
-You can associate a fixed or floating IP address with a server,
-or disassociate a fixed or floating IP address from a server.
+There are many actions available for a server:
 
-You can create an image from a server, create a backup of a server,
-and force-delete a server before deferred cleanup.
-You can lock, pause, reboot, rebuild, rescue, resize, resume, confirm
-the resize of, revert a pending resize for, shelve, shelf-offload,
-unshelve, start, stop, unlock, unpause, and unrescue a server. You can
-also change the password of the server and add a security group to or
-remove a security group from a server. You can also trigger a crash dump
-into a server since Mitaka release.
-
-You can get an serial, SPICE, or VNC console for a server.
+* You can associate and disassociate a fixed or floating IP address with
+  or from a server
+* You can create an image from a server
+* You can create a backup of a server
+* You can force-delete a server before deferred cleanup
+* You can lock, pause, reboot, rebuild, rescue, resize, resume, confirm
+  the resize of, revert a pending resize for, shelve, shelf-offload,
+  unshelve, start, stop, unlock, unpause, and unrescue a server
+* You can change the password of the server
+* You can add a security group to or remove a security group from a server
+* You can trigger a crash dump into a server
+* You can get a graphical or serial console for a server
 
+...among others.
 
 Add (Associate) Floating Ip (addFloatingIp Action) (DEPRECATED)
 ================================================================