[api-ref] Complete port name and shard documentation

Change-Id: I92da15361f203d2f973959a06e5d92394b29c016

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

@@ -111,6 +111,9 @@ This method requires a Node UUID and the physical hardware address for the Port
 .. versionadded:: 1.53
   Added the ``is_smartnic`` request and response fields.
 
+.. versionadded:: 1.88
+  Added the ``name`` field.
+
 Normal response code: 201
 
 Request
@@ -121,6 +124,7 @@ Request
     - node_uuid: req_node_uuid
     - address: req_port_address
     - portgroup_uuid: req_portgroup_uuid
+    - name: req_port_name
     - local_link_connection: req_local_link_connection
     - pxe_enabled: req_pxe_enabled
     - physical_network: req_physical_network
@@ -142,6 +146,7 @@ Response
     - address: port_address
     - node_uuid: node_uuid
     - portgroup_uuid: portgroup_uuid
+    - name: port_name
     - local_link_connection: local_link_connection
     - pxe_enabled: pxe_enabled
     - physical_network: physical_network
@@ -182,6 +187,13 @@ Return a list of bare metal Ports, with detailed information.
 .. versionadded:: 1.53
   Added the ``is_smartnic`` response fields.
 
+.. versionadded:: 1.82
+  Added the ability to filter ports based on the shard of the node they are
+  associated with.
+
+.. versionadded:: 1.88
+  Added the ``name`` field.
+
 Normal response code: 200
 
 Request
@@ -193,6 +205,7 @@ Request
     - node_uuid: r_port_node_uuid
     - portgroup: r_port_portgroup_ident
     - address: r_port_address
+    - shard: r_port_shard
     - limit: limit
     - marker: marker
     - sort_dir: sort_dir
@@ -208,6 +221,7 @@ Response
     - address: port_address
     - node_uuid: node_uuid
     - portgroup_uuid: portgroup_uuid
+    - name: port_name
     - local_link_connection: local_link_connection
     - pxe_enabled: pxe_enabled
     - physical_network: physical_network
@@ -248,6 +262,9 @@ Show details for the given Port.
 .. versionadded:: 1.53
   Added the ``is_smartnic`` response fields.
 
+.. versionadded:: 1.88
+  Added the ``name``
+
 Normal response code: 200
 
 Request
@@ -267,6 +284,7 @@ Response
     - address: port_address
     - node_uuid: node_uuid
     - portgroup_uuid: portgroup_uuid
+    - name: port_name
     - local_link_connection: local_link_connection
     - pxe_enabled: pxe_enabled
     - physical_network: physical_network
@@ -302,6 +320,10 @@ Update a Port.
 .. versionadded:: 1.53
   Added the ``is_smartnic`` fields.
 
+.. versionadded:: 1.88
+  Added the ``name``
+
+
 Normal response code: 200
 
 Request
@@ -328,6 +350,7 @@ Response
     - address: port_address
     - node_uuid: node_uuid
     - portgroup_uuid: portgroup_uuid
+    - name: port_name
     - local_link_connection: local_link_connection
     - pxe_enabled: pxe_enabled
     - physical_network: physical_network

api-ref/source/parameters.yaml

@@ -106,7 +106,7 @@ node_ident:
   type: string
 port_ident:
   description: |
-    The UUID of the port.
+    The UUID or Name of the port.
   in: path
   required: true
   type: string
@@ -1419,6 +1419,12 @@ port_address:
   in: body
   required: true
   type: string
+port_name:
+  description: |
+    The name assigned to the network Port.
+  in: body
+  required: false
+  type: string
 portgroup_address:
   description: |
     Physical hardware address of this Portgroup, typically the hardware
@@ -1786,6 +1792,12 @@ req_port_address:
   in: body
   required: true
   type: string
+req_port_name:
+  description: |
+    The name assigned to the network Port.
+  in: body
+  required: false
+  type: string
 req_portgroup_address:
   description: |
     Physical hardware address of this Portgroup, typically the hardware

api-ref/source/samples/port-create-request.json

@@ -1,6 +1,7 @@
 {
     "node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
     "portgroup_uuid": "e43c722c-248e-4c6e-8ce8-0d8ff129387a",
+    "name": "port1",
     "address": "11:11:11:11:11:11",
     "is_smartnic": true,
     "local_link_connection": {

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

@@ -19,6 +19,7 @@
     "switch_id": "0a:1b:2c:3d:4e:5f",
     "switch_info": "switch1"
   },
+  "name": "port1",
   "node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
   "physical_network": "physnet1",
   "portgroup_uuid": "e43c722c-248e-4c6e-8ce8-0d8ff129387a",

api-ref/source/samples/port-list-detail-response.json

@@ -21,6 +21,7 @@
         "switch_id": "0a:1b:2c:3d:4e:5f",
         "switch_info": "switch1"
       },
+      "name": "port1",
       "node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
       "physical_network": "physnet1",
       "portgroup_uuid": "e43c722c-248e-4c6e-8ce8-0d8ff129387a",

api-ref/source/samples/port-update-response.json

@@ -19,6 +19,7 @@
     "switch_id": "0a:1b:2c:3d:4e:5f",
     "switch_info": "switch1"
   },
+  "name": "port1",
   "node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
   "physical_network": "physnet1",
   "portgroup_uuid": "e43c722c-248e-4c6e-8ce8-0d8ff129387a",

ironic/api/controllers/v1/port.py

@@ -111,7 +111,7 @@ def hide_fields_in_newer_versions(port):
     # if requested version is < 1.53, hide is_smartnic field.
     if not api_utils.allow_port_is_smartnic():
         port.pop('is_smartnic', None)
-    # if requested version is < 1.69, hide name field.
+    # if requested version is < 1.88, hide name field.
     if not api_utils.allow_port_name():
         port.pop('name', None)