<div dir="ltr"><div><div><div><div><div><div>Hi,<br><br></div>I'd like to extend the information we produce with the Nova v3 API samples in order to make it easier to automate as much as possible the generation of a specification document. This should make it easier to keep the documentation more accurate and up to date in the future. I believe that if we generate a meta file for each xml and json response file which includes some information which describes the method for the api sample and ties together the request and response files we can do this.<br>
<br></div>I've put together a bit of a prototype here  (the patch is very ugly at the moment, just proof of concept)<br><br><a href="https://review.openstack.org/#/c/40169/">https://review.openstack.org/#/c/40169/</a><br>
<br></div>An example of the hosts extension method to put a host into or out of maintenance mode, a file called host-put-maintenance-resp.json.meta is created:<br> :<br><br>{<br>    "description": "Enables a host or puts it in maintenance mode.", <br>
    "extension": "os-hosts", <br>    "extension_description": "Manages physical hosts.", <br>    "method": "PUT", <br>    "request": "host-put-maintenance-req.json", <br>
    "response": "host-put-maintenance-resp.json", <br>    "section_name": "Hosts", <br>    "status": 200, <br>    "url": "os-hosts/{host_name}"<br>}<br>
<br></div>A separate metafile is created for each api sample response rather than trying to accumulate them by extension because this way it allows for the tests to still be run in parallel. The metafile also adds the logging of the status code expected which is not currently done and I think an important part of the API.<br>
<br></div><div>On the documentation side we'd have a script collate all the metafiles and produce the bulk of the specification document.<br></div><div><br></div>The changes to the api sample test code is fairly minor:<br>
<br>class HostsSampleJsonTest(api_sample_base.ApiSampleTestBaseV3):<br>    extension_name = "os-hosts"<br>    section_name = "Hosts"<br>    section_doc = "Manages physical hosts."<br><br>    def test_host_startup(self):<br>
        response = self._do_get(<br>            'os-hosts/%s/startup', self.compute.host, 'host_name',<br>            api_desc='Starts a host.')<br>        subs = self._get_regexes()<br>        self._verify_response('host-get-startup', subs, response, 200)<br>
<br>    def test_host_maintenance(self):<br>        response = self._do_put(<br>            'os-hosts/%s', self.compute.host, 'host_name',<br>            'host-put-maintenance-req', {},<br>            api_desc='Enables a host or puts it in maintenance mode.')<br>
        subs = self._get_regexes()<br>        self._verify_response('host-put-maintenance-resp', subs, response, 200)<br><br><br></div>- some definitions per extension and a description for the method per test so I don't think its a significant burden for developers or reviewers.<br>
<br><div><div><div>I'd like to know what people think about heading in this direction, and if there is any other information we should include. I'm not currently intending on including this in the first pass of porting the api samples tests to v3 (I don't think there is time) nor to backport to V2.<br>
<br></div><div>Regards,<br><br>Chris<br></div></div></div></div>