On 9 September 2015 at 03:43, Anne Gentle <annegen...@justwriteclick.com> wrote: > > > On Tue, Sep 8, 2015 at 8:41 PM, Ken'ichi Ohmichi <ken1ohmi...@gmail.com> > wrote: >> >> Hi Melanie, >> >> 2015-09-09 8:00 GMT+09:00 melanie witt <melwi...@gmail.com>: >> > Hi All, >> > >> > With usage of v2.1 picking up (devstack) I find myself going to the API >> > ref documentation [1] often and find it lacking compared with the similar >> > v2 >> > doc [2]. I refer to this doc whenever I see a novaclient bug where >> > something >> > broke with v2.1 and I'm trying to find out what the valid request >> > parameters >> > are, etc. >> > >> > The main thing I notice is in the v2.1 docs, there isn't any request >> > parameter list with descriptions like there is in v2. And I notice "create >> > server" documentation doesn't seem to exist -- there is "Create multiple >> > servers" but it doesn't provide much nsight about what the many request >> > parameters are. >> > >> > I assume the docs are generated from the code somehow, so I'm wondering >> > how we can get this doc improved? Any pointers would be appreciated. > > > They are manual, and Alex made a list of how far behind the 2.1 docs which > is in a doc bug here: > > https://bugs.launchpad.net/openstack-api-site/+bug/1488144 > > It's great to see Atsushi Sakai working hard on those, join him in the > patching. > > We're still patching WADL for this release with the hope of adding Swagger > for many services by October 15th -- however the WADL to Swagger tool we > have now migrates WADL.
Mel, thanks for raising this one, its super important. As I understand it from the API meeting I have dropped in on, some of this work is being tracked in here: https://etherpad.openstack.org/p/nova-v2.1-api-doc At the summit we agreed the focus as Docs and getting v2.1 on by default. That hasn't quite happened, but now is a good time to try and catch up on the API docs. All help really appreciated there. The recent issues with Horizon not working after upgrading python-novaclient seem to be highlighting the need for docs on how to use our client with the microversions too. Thanks, John > >> > >> > Thanks, >> > -melanie (irc: melwitt) >> > >> > >> > [1] http://developer.openstack.org/api-ref-compute-v2.1.html >> > [2] http://developer.openstack.org/api-ref-compute-v2.html >> >> Nice point. >> "create server" API is most important and necessary to be described on >> the document anyway. >> >> In short-term, we need to describe it from the code by hands, and we >> can know available parameters from JSON-Schema code. >> The base parameters can be gotten from >> >> https://github.com/openstack/nova/blob/master/nova/api/openstack/compute/schemas/servers.py#L18 >> In addition, there are extensions which add more parameters and we can >> get to know from >> >> https://github.com/openstack/nova/tree/master/nova/api/openstack/compute/schemas >> If module files contain the dict *server_create*, they are also API >> parameters. >> For example, keypairs extension adds "key_name" parameter and we can >> know it from >> https://github.com/openstack/nova/blob/master/nova/api/openstack/compute/schemas/keypairs.py >> >> In long-term, it will be great to generate these API parameter >> document from JSON-Schema directly. >> JSON-Schema supports "description" parameter and we can describe the >> meaning of each parameter. >> But that will be long-term way. We need to write them by hands now. >> >> Thanks >> Ken Ohmichi __________________________________________________________________________ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev