Open Stack

Hi,

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.

I've put together a bit of a prototype here  (the patch is very ugly at the
moment, just proof of concept)

https://review.openstack.org/#/c/40169/

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:
 :

{
    "description": "Enables a host or puts it in maintenance mode.",
    "extension": "os-hosts",
    "extension_description": "Manages physical hosts.",
    "method": "PUT",
    "request": "host-put-maintenance-req.json",
    "response": "host-put-maintenance-resp.json",
    "section_name": "Hosts",
    "status": 200,
    "url": "os-hosts/{host_name}"
}

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.

On the documentation side we'd have a script collate all the metafiles and
produce the bulk of the specification document.

The changes to the api sample test code is fairly minor:

class HostsSampleJsonTest(api_sample_base.ApiSampleTestBaseV3):
    extension_name = "os-hosts"
    section_name = "Hosts"
    section_doc = "Manages physical hosts."

    def test_host_startup(self):
        response = self._do_get(
            'os-hosts/%s/startup', self.compute.host, 'host_name',
            api_desc='Starts a host.')
        subs = self._get_regexes()
        self._verify_response('host-get-startup', subs, response, 200)

    def test_host_maintenance(self):
        response = self._do_put(
            'os-hosts/%s', self.compute.host, 'host_name',
            'host-put-maintenance-req', {},
            api_desc='Enables a host or puts it in maintenance mode.')
        subs = self._get_regexes()
        self._verify_response('host-put-maintenance-resp', subs, response,
200)


- 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.

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.

Regards,

Chris
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20130805/22399ca3/attachment.html>