From 95a449357cbbaf5c34b810a470a5bfda447a15f5 Mon Sep 17 00:00:00 2001
From: Yolanda Robla <yroblamo@redhat.com>
Date: Tue, 24 Jul 2018 13:40:44 +0200
Subject: [PATCH] Add documentation for BIOS settings
Update api-ref documentation, to add the BIOS
settings.
Change-Id: Ic592b5fa39f0d19d5676906ecd5c8fcbebf8e25f
---
api-ref/regenerate-samples.sh | 2 +
.../source/baremetal-api-v1-nodes-bios.inc | 84 +++++++++++++++++++
api-ref/source/index.rst | 1 +
api-ref/source/parameters.yaml | 32 +++++++
.../samples/node-bios-detail-response.json | 18 ++++
.../samples/node-bios-list-response.json | 20 +++++
6 files changed, 157 insertions(+)
create mode 100644 api-ref/source/baremetal-api-v1-nodes-bios.inc
create mode 100644 api-ref/source/samples/node-bios-detail-response.json
create mode 100644 api-ref/source/samples/node-bios-list-response.json
diff --git a/api-ref/regenerate-samples.sh b/api-ref/regenerate-samples.sh
index 9b856a1426..aebcd5f78f 100755
--- a/api-ref/regenerate-samples.sh
+++ b/api-ref/regenerate-samples.sh
@@ -15,6 +15,7 @@ IRONIC_API_VERSION="1.37"
export OS_AUTH_TOKEN IRONIC_URL
+DOC_BIOS_UUID="dff29d23-1ded-43b4-8ae1-5eebb3e30de1"
DOC_CHASSIS_UUID="dff29d23-1ded-43b4-8ae1-5eebb3e30de1"
DOC_NODE_UUID="6d85703a-565d-469a-96ce-30b6de53079d"
DOC_DYNAMIC_NODE_UUID="2b045129-a906-46af-bc1a-092b294b3428"
@@ -303,6 +304,7 @@ GET v1/nodes/$NID/volume/targets?detail=True > node-volume-target-detail-respons
#####################
# Replace automatically generated UUIDs by already used in documentation
+sed -i "s/$BID/$DOC_BIOS_UUID/" *.json
sed -i "s/$CID/$DOC_CHASSIS_UUID/" *.json
sed -i "s/$NID/$DOC_NODE_UUID/" *.json
sed -i "s/$DNID/$DOC_DYNAMIC_NODE_UUID/" *.json
diff --git a/api-ref/source/baremetal-api-v1-nodes-bios.inc b/api-ref/source/baremetal-api-v1-nodes-bios.inc
new file mode 100644
index 0000000000..4602b134b5
--- /dev/null
+++ b/api-ref/source/baremetal-api-v1-nodes-bios.inc
@@ -0,0 +1,84 @@
+.. -*- rst -*-
+
+=================
+Node Bios (nodes)
+=================
+
+.. versionadded:: 1.40
+
+Given a Node identifier (``uuid`` or ``name``), the API exposes the list of
+all Bios settings associated with that Node.
+
+These endpoints do not allow modification of the Bios settings; that should be
+done by using ``clean steps``.
+
+List all Bios settings by Node
+==============================
+
+.. rest_method:: GET /v1/nodes/{node_ident}/bios
+
+Return a list of Bios settings associated with ``node_ident``.
+
+Normal response code: 200
+
+Error codes: 404
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+ - node_ident: node_ident
+
+Response
+--------
+
+.. rest_parameters:: parameters.yaml
+
+ - bios: bios_settings
+ - created_at: created_at
+ - updated_at: updated_at
+ - links: links
+ - name: bios_setting_name
+ - value: bios_setting_value
+
+**Example list of a Node's Bios settings:**
+
+.. literalinclude:: samples/node-bios-list-response.json
+
+
+Show single Bios setting of a Node
+==================================
+
+.. rest_method:: GET /v1/nodes/{node_ident}/bios/{bios_setting}
+
+Return the content of the specific bios ``bios_setting`` associated with
+``node_ident``.
+
+Normal response code: 200
+
+Error codes: 404
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+ - node_ident: node_ident
+ - bios_setting: bios_setting
+
+Response
+--------
+
+.. rest_parameters:: parameters.yaml
+
+ - <key>: d_bios_setting
+ - created_at: created_at
+ - updated_at: updated_at
+ - links: links
+ - name: bios_setting_name
+ - value: bios_setting_value
+
+**Example details of a Node's Bios setting details:**
+
+.. literalinclude:: samples/node-bios-detail-response.json
diff --git a/api-ref/source/index.rst b/api-ref/source/index.rst
index e58a9d92ef..c47f178bc5 100644
--- a/api-ref/source/index.rst
+++ b/api-ref/source/index.rst
@@ -23,4 +23,5 @@
.. include:: baremetal-api-v1-driver-passthru.inc
.. include:: baremetal-api-v1-chassis.inc
.. include:: baremetal-api-v1-misc.inc
+.. include:: baremetal-api-v1-nodes-bios.inc
diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml
index f3f2eb6dc2..a25962e8a9 100644
--- a/api-ref/source/parameters.yaml
+++ b/api-ref/source/parameters.yaml
@@ -38,6 +38,12 @@ x-openstack-ironic-api-version:
type: string
# variables in path
+bios_setting:
+ description: |
+ The name of the Bios setting.
+ in: path
+ required: true
+ type: string
chassis_ident:
description: |
The UUID of the chassis.
@@ -343,6 +349,25 @@ agent_node:
type: JSON
# variables in the API body
+bios_setting_name:
+ description: |
+ The name of a Bios setting for a Node, eg. "virtualization".
+ in: body
+ required: true
+ type: string
+bios_setting_value:
+ description: |
+ The value of a Bios setting for a Node, eg. "on".
+ in: body
+ required: true
+ type: string
+bios_settings:
+ description: |
+ Optional list of one or more Bios settings. It includes following fields
+ "created_at", "updated_at", "links", "name", "value".
+ in: body
+ required: true
+ type: array
boot_device:
description: |
The boot device for a Node, eg. "pxe" or "disk".
@@ -409,6 +434,13 @@ created_at:
in: body
required: true
type: string
+d_bios_setting:
+ description: |
+ Dictionary containing the definition of a Bios setting. It includes the
+ following fields "created_at", "updated_at", "links", "name", "value".
+ in: body
+ required: true
+ type: dictionary
default_boot_interface:
description: |
The default boot interface used for a node with a dynamic driver, if no
diff --git a/api-ref/source/samples/node-bios-detail-response.json b/api-ref/source/samples/node-bios-detail-response.json
new file mode 100644
index 0000000000..a7b01028cc
--- /dev/null
+++ b/api-ref/source/samples/node-bios-detail-response.json
@@ -0,0 +1,18 @@
+{
+ "virtualization": {
+ "created_at": "2016-08-18T22:28:49.653974+00:00",
+ "updated_at": "2016-08-18T22:28:49.653974+00:00",
+ "links": [
+ {
+ "href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/bios/virtualization",
+ "rel": "self"
+ },
+ {
+ "href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/bios/virtualization",
+ "rel": "bookmark"
+ }
+ ],
+ "name": "virtualization",
+ "value": "on"
+ }
+}
diff --git a/api-ref/source/samples/node-bios-list-response.json b/api-ref/source/samples/node-bios-list-response.json
new file mode 100644
index 0000000000..87d5e9c898
--- /dev/null
+++ b/api-ref/source/samples/node-bios-list-response.json
@@ -0,0 +1,20 @@
+{
+ "bios": [
+ {
+ "created_at": "2016-08-18T22:28:49.653974+00:00",
+ "updated_at": "2016-08-18T22:28:49.653974+00:00",
+ "links": [
+ {
+ "href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/bios/virtualization",
+ "rel": "self"
+ },
+ {
+ "href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/bios/virtualization",
+ "rel": "bookmark"
+ }
+ ],
+ "name": "virtualization",
+ "value": "on"
+ }
+ ]
+}