Open Stack

Hi,

For those who are interested, just an update on what we're doing to
generate a nova v3 api spec document.

All of the tests which generate api samples have been submitted to the
Nova review queue, though with everything going on I expect them to take
a while to merge. These changesets create api samples the same way that
the V2 API ones were created.

However, we are aiming to as much as possible autogenerate the
specification document. The aim of this being to reduce future
documentation workload, reduce the error rate and ensure the
documentation stays in sync with the code in the future.

In order to do that I've submitted a patch which adds some
infrastructure to the api sample tests (V3 only) which allows the test
writer to specify additional information such as a description of the
API method they are testing, the extension and how the url is
generated. When the API samples are created a metafile with this
information which also links to the appropriate api samples. Something
like this:

{
    "description": "Updates an agent build", 
    "extension": "os-agents", 
    "extension_description": "Creates, updates, and deletes guest
agents. Use guest agents to access files on the disk, configure
networking, or run other applications or scripts in the guest while it
runs. This hypervisor-specific extension is not currently enabled for
KVM. Use of guest agents is possible only if the underlying service provider uses the Xen driver. ", 
    "method": "PUT", 
    "request": "agent-update-put-req.json", 
    "response": "agent-update-put-resp.json", 
    "section_name": "Guest Agents", 
    "status": 200, 
    "url": "os-agents/{id}"
}

The idea is that a script (not yet written) can pick up all these meta
files and then generate the equivalent of what is a api.openstack.org
for the V2 spec. The Nova patch is here (still WIP): 

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

It does mean that we need to make another pass over the api sample
tests for V3 to add this extra information and given that we can't
really do that (esp merge 40169) at this stage of Havana development
we'll be initially doing development on github here (some stuff
has already been added here) and then merge as early in the icehouse
cycle as we can.

https://github.com/cyeoh/nova-v3-api-doc

This will hopefully allow us to generate a V3 API spec document sooner
than we would otherwise be able if we waited until everything merged,
even if its not generated from the 'real' Nova tree.

Please let me know if you have any questions/suggestions. One thing
which hasn't been addressed is translation. I'm not sure exactly at
what point that should be done, but I don't think it makes sense to
generate metafiles in different languages in the nova tree.

Regards,

Chris