[openstack-dev] [nova] Autogenerating the Nova v3 API specification

Anne Gentle annegentle at justwriteclick.com
Mon Aug 5 14:15:33 UTC 2013


On Mon, Aug 5, 2013 at 8:55 AM, John Garbutt <john at johngarbutt.com> wrote:

> Given we seem to be leaning towards WSME:
> http://lists.openstack.org/pipermail/openstack-dev/2013-August/012954.html
>
> Could we not try to make WSME give us the documentation we need?
>
> Not sure if its feasible, but it seems like there is a good start to
> that already available:
> https://wsme.readthedocs.org/en/latest/document.html
>
>
John, this looks interesting, but I have reservations. Do you know if you
can suppress the SOAP and ExtDirect entries?

Also we already have available the current way to create API docs for
http://api.openstack.org/api-ref.html.

I'm not excited about an inconsistent user experience for reading REST API
docs for one project but not others. Where will it be published? How will
readers find it? And so on. It's good for Compute to lead the way and try
things, but I'd like to know if other projects are willing to follow?
Looking for input from other projects.

Anne


> John
>
> On 5 August 2013 08:44, Christopher Yeoh <cbkyeoh at gmail.com> wrote:
> > 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.
>

Wow what's your guess on how many files this will be? Trying to think of
this from a doc management standpoint for troubleshooting when the output
is incorrect.


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

I'd like to see the results of that script, and it's good you're thinking
about docs. But if you create the docs from the code it's not quite a spec,
what if the code is incorrect? Maybe I misunderstand.


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

I fully support these efforts, and I just want to be sure I understand the
eventual outcomes and ramifications.
Thanks,
Anne


>  > Regards,
> >
> > Chris
> >
> > _______________________________________________
> > OpenStack-dev mailing list
> > OpenStack-dev at lists.openstack.org
> > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
> >
>
> _______________________________________________
> OpenStack-dev mailing list
> OpenStack-dev at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>



-- 
Anne Gentle
annegentle at justwriteclick.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20130805/813ff5e0/attachment.html>


More information about the OpenStack-dev mailing list