Add description field to node: api-ref

Update api-ref to include the description field.

Also updated a few missing owner field.

Change-Id: I81c5bf1be18ac4109f0e5ef66193ff66f484d107
Story: 2003089
Task: 23178

api-ref/source/baremetal-api-v1-nodes.inc

@@ -92,9 +92,12 @@ supplied when the Node is created, or the resource may be updated later.
 .. versionadded:: 1.46
   Introduced the ``conductor_group`` field.
 
-.. versionadded: 1.50
+.. versionadded:: 1.50
   Introduced the ``owner`` field.
 
+.. versionadded:: 1.51
+  Introduced the ``description`` field.
+
 Normal response codes: 201
 
 Error codes: 400,403,406
@@ -124,6 +127,7 @@ Request
    - uuid: req_uuid
    - vendor_interface: req_vendor_interface
    - owner: owner
+   - description: n_description
 
 **Example Node creation request with a dynamic driver:**
 
@@ -193,6 +197,7 @@ microversion 1.48.
     - protected: protected
     - protected_reason: protected_reason
     - owner: owner
+    - description: n_description
 
 **Example JSON representation of a Node:**
 
@@ -240,9 +245,12 @@ provision state, and maintenance setting for each Node.
   Introduced the ``conductor_group`` request parameter, to allow filtering the
   list of returned nodes by conductor group.
 
-.. versionadded: 1.50
+.. versionadded:: 1.50
   Introduced the ``owner`` field.
 
+.. versionadded:: 1.51
+  Introduced the ``description`` field.
+
 Normal response codes: 200
 
 Error codes: 400,403,406
@@ -260,13 +268,14 @@ Request
    - resource_class: r_resource_class
    - conductor_group: r_conductor_group
    - fault: r_fault
+   - owner: owner
+   - description_contains: r_description_contains
    - fields: fields
    - limit: limit
    - marker: marker
    - sort_dir: sort_dir
    - sort_key: sort_key
    - detail: detail
-   - owner: owner
 
 Response
 --------
@@ -316,9 +325,12 @@ Nova instance, eg. with a request to ``v1/nodes/detail?instance_uuid={NOVA INSTA
 .. versionadded:: 1.48
   Introduced the ``protected`` and ``protected_reason`` fields.
 
-.. versionadded: 1.50
+.. versionadded:: 1.50
   Introduced the ``owner`` field.
 
+.. versionadded:: 1.51
+  Introduced the ``description`` field.
+
 Normal response codes: 200
 
 Error codes: 400,403,406
@@ -337,6 +349,7 @@ Request
    - resource_class: r_resource_class
    - conductor_group: r_conductor_group
    - owner: owner
+   - description_contains: r_description_contains
    - limit: limit
    - marker: marker
    - sort_dir: sort_dir
@@ -392,6 +405,8 @@ Response
     - conductor_group: conductor_group
     - protected: protected
     - protected_reason: protected_reason
+    - owner: owner
+    - description: n_description
 
 **Example detailed list of Nodes:**
 
@@ -423,6 +438,12 @@ only the specified set.
 .. versionadded:: 1.48
   Introduced the ``protected`` and ``protected_reason`` fields.
 
+.. versionadded:: 1.50
+  Introduced the ``owner`` field.
+
+.. versionadded:: 1.51
+  Introduced the ``description`` field.
+
 Normal response codes: 200
 
 Error codes: 400,403,404,406
@@ -485,6 +506,8 @@ Response
     - conductor_group: conductor_group
     - protected: protected
     - protected_reason: protected_reason
+    - owner: owner
+    - description: n_description
 
 **Example JSON representation of a Node:**
 
@@ -505,6 +528,9 @@ managed through sub-resources.
 .. versionadded:: 1.25
   Introduced the ability to unset a node's chassis UUID.
 
+.. versionadded:: 1.51
+  Introduced the ability to set/unset a node's description.
+
 Normal response codes: 200
 
 Error codes: 400,403,404,406,409
@@ -573,6 +599,8 @@ Response
     - conductor_group: conductor_group
     - protected: protected
     - protected_reason: protected_reason
+    - owner: owner
+    - description: n_description
 
 **Example JSON representation of a Node:**
 

api-ref/source/parameters.yaml

@@ -205,6 +205,13 @@ r_conductor_group:
   in: query
   required: false
   type: string
+r_description_contains:
+  description: |
+    Filter the list of returned nodes, and only return those containing
+    substring specified by ``description_contains``.
+  in: query
+  requred: false
+  type: string
 r_driver:
   description: |
     Filter the list of returned nodes, and only return those with the specified
@@ -766,6 +773,12 @@ management_interface:
   in: body
   required: true
   type: string
+n_description:
+  description: |
+    Informational text about this node.
+  in: body
+  required: true
+  type: string
 n_portgroups:
   description: |
     Links to the collection of portgroups on this node.

api-ref/source/samples/node-create-response.json

@@ -8,6 +8,7 @@
   "created_at": "2016-08-18T22:28:48.643434+11:11",
   "deploy_interface": null,
   "deploy_step": {},
+  "description": null,
   "driver": "agent_ipmitool",
   "driver_info": {
     "ipmi_password": "******",

api-ref/source/samples/node-show-response.json

@@ -8,6 +8,7 @@
   "created_at": "2016-08-18T22:28:48.643434+11:11",
   "deploy_interface": null,
   "deploy_step": {},
+  "description": null,
   "driver": "fake",
   "driver_info": {
     "ipmi_password": "******",

api-ref/source/samples/nodes-list-details-response.json

@@ -10,6 +10,7 @@
       "created_at": "2016-08-18T22:28:48.643434+11:11",
       "deploy_interface": null,
       "deploy_step": {},
+      "description": null,
       "driver": "fake",
       "driver_info": {
         "ipmi_password": "******",