api-ref: Example verification for servers-actions.inc

* Example for the rebuild action

  The functional test is modified and
  the example is replaced with v2.26 examples.

* Example for the rescue action

  The example in API reference is replaced with
  the example with 'rescue_imgae_ref'.

Parameters for the rebuild action and the rescue action
are also fixed.

The patch completes the parameter verification and
the example verification of servers-actions.inc.

Change-Id: Iaf8808b13d1fdfead50da4cd447b3893578f76dd
Implements: blueprint api-ref-in-rst-pike

api-ref/source/parameters.yaml

@@ -11,6 +11,13 @@ image_location:
   required: true
   type: string
   max_version: 2.44
+server_location:
+  description: |
+    The location URL of the server, HTTP header
+    "Location: <server location URL>" will be returned.
+  in: header
+  required: true
+  type: string
 tag_location:
   description: |
     The location of the tag. It's individual tag URL which can be used for
@@ -1045,10 +1052,10 @@ address:
 addresses:
   description: |
     The addresses for the server.  Addresses information is hidden for any server
-    in a state set in the ``osapi_hide_server_address_states`` configuration option.
+    in a state set in the ``hide_server_address_states`` configuration option.
     By default, servers in ``building`` state hide their addresses information.
     See ``nova.conf`` `configuration options
-    <http://docs.openstack.org/liberty/config-reference/content/list-of-compute-config-options.html>`_
+    <https://docs.openstack.org/ocata/config-reference/compute/config-options.html>`_
     for more information.
   in: body
   required: true
@@ -2779,6 +2786,13 @@ imageRef:
   in: body
   required: true
   type: string
+imageRef_rebuild:
+  description: |
+    The UUID of the image to rebuild for your server instance.
+    It must be a valid UUID otherwise API will return 400.
+  in: body
+  required: true
+  type: string
 images:
   description: |
     An array of Image objects.
@@ -3849,7 +3863,7 @@ path:
   description: |
     The path field in the personality object.
   in: body
-  required: false
+  required: true
   type: string
 pause:
   description: |
@@ -3878,7 +3892,7 @@ personality:
     of allowed bytes in the decoded, rather than encoded, data.
   in: body
   required: false
-  type: string
+  type: array
 policies:
   description: |
     A list of exactly one policy name to associate with the server group. The
@@ -4061,10 +4075,10 @@ reboot_type:
   type: string
 rebuild:
   description: |
-    The action.
+    The action to rebuild a server.
   in: body
   required: true
-  type: string
+  type: object
 remote_console:
   description: |
     The remote console object.
@@ -4126,10 +4140,10 @@ request_id_body:
   type: string
 rescue:
   description: |
-    The action.
+    The action to rescue a server.
   in: body
   required: true
-  type: string
+  type: object
 rescue_image_ref:
   description: |
     The image reference to use to rescue your server instance. Specify the image reference
@@ -4341,6 +4355,14 @@ server_description:
     A free form description of the server. Limited to 255 characters
     in length. Before microversion 2.19 this was set to the server
     name.
+server_description_resp:
+  description: |
+    The description of the server.
+    Before microversion 2.19 this was set to the server name.
+  in: body
+  required: true
+  type: string
+  min_version: 2.19
 server_group:
   description: |
     The server group obejct.
@@ -4431,6 +4453,15 @@ server_launch_index:
     When servers are launched via multiple create, this is the
     sequence in which the servers were launched.
   min_version: 2.3
+server_links:
+  description: |
+    Links pertaining to the server. See `API Guide / Links and
+    References
+    <http://developer.openstack.org/api-guide/compute/links_and_references.html>`_
+    for more info.
+  in: body
+  type: array
+  required: true
 server_name:
   description: |
     The server name.

api-ref/source/servers-actions.inc

@@ -1,6 +1,4 @@
 .. -*- rst -*-
-.. needs:parameter_verification
-.. needs:example_verification
 .. needs:body_verification
 
 ===========================================
@@ -475,26 +473,60 @@ Request
 
   - server_id: server_id_path
   - rebuild: rebuild
-  - imageRef: imageRef
+  - imageRef: imageRef_rebuild
-  - name: server_name_optional
+  - accessIPv4: accessIPv4_in
+  - accessIPv6: accessIPv6_in
   - adminPass: adminPass_request
   - metadata: metadata
+  - name: server_name_optional
+  - OS-DCF:diskConfig: OS-DCF:diskConfig
   - personality: personality
+  - personality.path: path
+  - personality.contents: contents
   - preserve_ephemeral: preserve_ephemeral
+  - description: server_description
 
-**Example Rebuild Server (rebuild Action)**
+**Example Rebuild Server (rebuild Action) (v2.26)**
 
-Preserving the ephemeral disk
+.. literalinclude:: ../../doc/api_samples/servers/v2.26/server-action-rebuild.json
-
-.. literalinclude:: ../../doc/api_samples/servers/server-action-rebuild-preserve-ephemeral.json
    :language: javascript
 
 Response
 --------
 
-**Example Rebuild Server (rebuild Action)**
+.. rest_parameters:: parameters.yaml
 
-.. literalinclude:: ../../doc/api_samples/servers/server-action-rebuild-resp.json
+  - Location: server_location
+  - server: server
+  - accessIPv4: accessIPv4
+  - accessIPv6: accessIPv6
+  - addresses: addresses_obj
+  - adminPass: adminPass_response
+  - created: created
+  - flavor: flavor
+  - flavor.id: flavor_id_body
+  - flavor.links: links
+  - hostId: hostId
+  - id: server_id
+  - image: image
+  - image.id: image_id_body
+  - image.links: links
+  - links: server_links
+  - metadata: metadata_object
+  - name: server_name
+  - OS-DCF:diskConfig: disk_config
+  - progress: progress
+  - status: server_status
+  - tenant_id: tenant_id_body
+  - updated: updated
+  - user_id: user_id
+  - locked: locked
+  - description: server_description_resp
+  - tags: tags
+
+**Example Rebuild Server (rebuild Action) (v2.26)**
+
+.. literalinclude:: ../../doc/api_samples/servers/v2.26/server-action-rebuild-resp.json
    :language: javascript
 
 Remove (Disassociate) Floating Ip (removeFloatingIp Action) (DEPRECATED)
@@ -607,9 +639,9 @@ Request
   - adminPass: adminPass_rescue_request
   - rescue_image_ref: rescue_image_ref
 
-**Example Rescue server**
+**Example Rescue server (rescue Action)**
 
-.. literalinclude:: ../../doc/api_samples/os-rescue/server-rescue-req.json
+.. literalinclude:: ../../doc/api_samples/os-rescue/server-rescue-req-with-image-ref.json
    :language: javascript
 
 Response
@@ -619,7 +651,7 @@ Response
 
   - adminPass: adminPass_response
 
-**Example Extended rescue server**
+**Example Rescue server (rescue Action)**
 
 .. literalinclude:: ../../doc/api_samples/os-rescue/server-rescue.json
    :language: javascript

doc/api_samples/servers/v2.26/server-action-rebuild-resp.json

@@ -0,0 +1,59 @@
+{
+    "server": {
+        "accessIPv4": "1.2.3.4",
+        "accessIPv6": "80fe::",
+        "addresses": {
+            "private": [
+                {
+                    "addr": "192.168.0.3",
+                    "version": 4
+                }
+            ]
+        },
+        "adminPass": "seekr3t",
+        "created": "2013-11-14T06:29:00Z",
+        "flavor": {
+            "id": "1",
+            "links": [
+                {
+                    "href": "http://openstack.example.com/6f70656e737461636b20342065766572/flavors/1",
+                    "rel": "bookmark"
+                }
+            ]
+        },
+        "hostId": "28d8d56f0e3a77e20891f455721cbb68032e017045e20aa5dfc6cb66",
+        "id": "a0a80a94-3d81-4a10-822a-daa0cf9e870b",
+        "image": {
+            "id": "70a599e0-31e7-49b7-b260-868f441e862b",
+            "links": [
+                {
+                    "href": "http://openstack.example.com/6f70656e737461636b20342065766572/images/70a599e0-31e7-49b7-b260-868f441e862b",
+                    "rel": "bookmark"
+                }
+            ]
+        },
+        "links": [
+            {
+                "href": "http://openstack.example.com/v2/6f70656e737461636b20342065766572/servers/a0a80a94-3d81-4a10-822a-daa0cf9e870b",
+                "rel": "self"
+            },
+            {
+                "href": "http://openstack.example.com/6f70656e737461636b20342065766572/servers/a0a80a94-3d81-4a10-822a-daa0cf9e870b",
+                "rel": "bookmark"
+            }
+        ],
+        "metadata": {
+            "meta_var": "meta_val"
+        },
+        "name": "foobar",
+        "OS-DCF:diskConfig": "AUTO",
+        "progress": 0,
+        "status": "ACTIVE",
+        "tenant_id": "6f70656e737461636b20342065766572",
+        "updated": "2013-11-14T06:29:02Z",
+        "user_id": "fake",
+        "locked": false,
+        "description" : "description of foobar",
+        "tags": ["tag1", "tag2"]
+    }
+}

doc/api_samples/servers/v2.26/server-action-rebuild.json

@@ -1,17 +1,21 @@
 {
     "rebuild" : {
         "imageRef" : "70a599e0-31e7-49b7-b260-868f441e862b",
-        "name" : "foobar",
+        "accessIPv4" : "1.2.3.4",
+        "accessIPv6" : "80fe::",
         "adminPass" : "seekr3t",
         "metadata" : {
             "meta_var" : "meta_val"
         },
+        "name" : "foobar",
+        "OS-DCF:diskConfig": "AUTO",
         "personality" : [
             {
                 "path" : "/etc/banner.txt",
                 "contents" : "ICAgICAgDQoiQSBjbG91ZCBkb2VzIG5vdCBrbm93IHdoeSBp dCBtb3ZlcyBpbiBqdXN0IHN1Y2ggYSBkaXJlY3Rpb24gYW5k IGF0IHN1Y2ggYSBzcGVlZC4uLkl0IGZlZWxzIGFuIGltcHVs c2lvbi4uLnRoaXMgaXMgdGhlIHBsYWNlIHRvIGdvIG5vdy4g QnV0IHRoZSBza3kga25vd3MgdGhlIHJlYXNvbnMgYW5kIHRo ZSBwYXR0ZXJucyBiZWhpbmQgYWxsIGNsb3VkcywgYW5kIHlv dSB3aWxsIGtub3csIHRvbywgd2hlbiB5b3UgbGlmdCB5b3Vy c2VsZiBoaWdoIGVub3VnaCB0byBzZWUgYmV5b25kIGhvcml6 b25zLiINCg0KLVJpY2hhcmQgQmFjaA=="
             }
         ],
-        "preserve_ephemeral": true
+        "preserve_ephemeral": false,
+        "description" : "description of foobar"
     }
 }

nova/tests/functional/api_sample_tests/api_samples/servers/v2.26/server-action-rebuild-resp.json.tpl

@@ -0,0 +1,59 @@
+{
+    "server": {
+        "accessIPv4": "%(access_ip_v4)s",
+        "accessIPv6": "%(access_ip_v6)s",
+        "addresses": {
+            "private": [
+                {
+                    "addr": "%(ip)s",
+                    "version": 4
+                }
+            ]
+        },
+        "adminPass": "%(password)s",
+        "created": "%(isotime)s",
+        "flavor": {
+            "id": "1",
+            "links": [
+                {
+                    "href": "%(compute_endpoint)s/flavors/1",
+                    "rel": "bookmark"
+                }
+            ]
+        },
+        "hostId": "%(hostid)s",
+        "id": "%(uuid)s",
+        "image": {
+            "id": "%(uuid)s",
+            "links": [
+                {
+                    "href": "%(compute_endpoint)s/images/%(uuid)s",
+                    "rel": "bookmark"
+                }
+            ]
+        },
+        "links": [
+            {
+                "href": "%(versioned_compute_endpoint)s/servers/%(uuid)s",
+                "rel": "self"
+            },
+            {
+                "href": "%(compute_endpoint)s/servers/%(uuid)s",
+                "rel": "bookmark"
+            }
+        ],
+        "metadata": {
+            "meta_var": "meta_val"
+        },
+        "name": "%(name)s",
+        "OS-DCF:diskConfig": "%(disk_config)s",
+        "progress": 0,
+        "status": "ACTIVE",
+        "tenant_id": "6f70656e737461636b20342065766572",
+        "updated": "%(isotime)s",
+        "user_id": "fake",
+        "locked": false,
+        "description": "%(description)s",
+        "tags": ["tag1", "tag2"]
+    }
+}

nova/tests/functional/api_sample_tests/api_samples/servers/v2.26/server-action-rebuild.json.tpl

@@ -0,0 +1,21 @@
+{
+    "rebuild" : {
+        "imageRef" : "%(uuid)s",
+        "accessIPv4" : "%(access_ip_v4)s",
+        "accessIPv6" : "%(access_ip_v6)s",
+        "adminPass" : "%(pass)s",
+        "metadata" : {
+            "meta_var" : "meta_val"
+        },
+        "name" : "%(name)s",
+        "OS-DCF:diskConfig": "%(disk_config)s",
+        "personality" : [
+            {
+                "path" : "/etc/banner.txt",
+                "contents" : "ICAgICAgDQoiQSBjbG91ZCBkb2VzIG5vdCBrbm93IHdoeSBp dCBtb3ZlcyBpbiBqdXN0IHN1Y2ggYSBkaXJlY3Rpb24gYW5k IGF0IHN1Y2ggYSBzcGVlZC4uLkl0IGZlZWxzIGFuIGltcHVs c2lvbi4uLnRoaXMgaXMgdGhlIHBsYWNlIHRvIGdvIG5vdy4g QnV0IHRoZSBza3kga25vd3MgdGhlIHJlYXNvbnMgYW5kIHRo ZSBwYXR0ZXJucyBiZWhpbmQgYWxsIGNsb3VkcywgYW5kIHlv dSB3aWxsIGtub3csIHRvbywgd2hlbiB5b3UgbGlmdCB5b3Vy c2VsZiBoaWdoIGVub3VnaCB0byBzZWUgYmV5b25kIGhvcml6 b25zLiINCg0KLVJpY2hhcmQgQmFjaA=="
+            }
+        ],
+        "preserve_ephemeral": %(preserve_ephemeral)s,
+        "description" : "%(description)s"
+    }
+}

nova/tests/functional/api_sample_tests/test_servers.py

@@ -387,6 +387,38 @@ class ServersActionsJson219Test(ServersSampleBase):
         self._verify_response('server-action-rebuild-resp', subs, resp, 202)
 
 
+class ServersActionsJson226Test(ServersSampleBase):
+    microversion = '2.26'
+    scenarios = [('v2_26', {'api_major_version': 'v2.1'})]
+
+    def test_server_rebuild(self):
+        uuid = self._post_server()
+        image = fake.get_valid_image_id()
+        params = {
+            'uuid': image,
+            'access_ip_v4': '1.2.3.4',
+            'access_ip_v6': '80fe::',
+            'disk_config': 'AUTO',
+            'hostid': '[a-f0-9]+',
+            'name': 'foobar',
+            'pass': 'seekr3t',
+            'preserve_ephemeral': 'false',
+            'description': 'description of foobar'
+        }
+
+        # Add 'tag1' and 'tag2' tags
+        self._do_put('servers/%s/tags/tag1' % uuid)
+        self._do_put('servers/%s/tags/tag2' % uuid)
+
+        # Rebuild Action
+        resp = self._do_post('servers/%s/action' % uuid,
+                             'server-action-rebuild', params)
+
+        subs = params.copy()
+        del subs['uuid']
+        self._verify_response('server-action-rebuild-resp', subs, resp, 202)
+
+
 class ServersCreateImageJsonTest(ServersSampleBase,
                                  _ServersActionsJsonTestMixin):
     """Tests the createImage server action API against 2.1."""