Add soft reboot, soft power off and power timeout to api-ref

This patch updates api-ref documentation with soft reboot, soft power
off and power timeout that were added in API microversion 1.27.

Partial-Bug: #1526226
Change-Id: I9b17da3e5e02f7e3de0c5c2b3dec1e81bf642391

api-ref/source/baremetal-api-v1-node-management.inc

@@ -296,11 +296,11 @@ Change Node Power State
 
 Request a change to the Node's power state.
 
-Normal response code: 202
+Normal response code: 202 (Accepted)
 
 Error codes:
     - 409 (NodeLocked, ClientError)
-    - 400 (InvalidState)
+    - 400 (Invalid, InvalidStateRequested, InvalidParameterValue)
     - 406 (NotAcceptable)
     - 503 (NoFreeConductorWorkers)
 
@@ -310,12 +310,17 @@ Request
 .. rest_parameters:: parameters.yaml
 
     - node_ident: node_ident
-    - target: power_state
+    - target: target_power_state
+    - timeout: power_timeout
 
 **Example request to power off a Node:**
 
 .. literalinclude:: samples/node-set-power-off.json
 
+**Example request to soft power off a Node with timeout:**
+
+.. literalinclude:: samples/node-set-soft-power-off.json
+
 
 Change Node Provision State
 ===========================

api-ref/source/parameters.yaml

@@ -644,6 +644,12 @@ power_state:
   in: body
   required: true
   type: string
+power_timeout:
+  description: |
+    Timeout for a power state transition. Added in API microversion 1.27.
+  in: body
+  required: false
+  type: integer
 properties:
   description: |
     A list of links to driver properties.
@@ -728,7 +734,9 @@ supported_boot_devices:
 target_power_state:
   description: |
     If a power state transition has been requested, this field represents the
-    requested (ie, "target") state.
+    requested (ie, "target") state either "power on", "power off", or "rebooting".
+    Added new target power states "soft power off" and "soft rebooting" in API
+    microversion 1.27.
   in: body
   required: true
   type: string

api-ref/source/samples/node-set-soft-power-off.json

@@ -0,0 +1,4 @@
+{
+    "target": "soft power off",
+    'timeout': 300
+}