Hi Melanie, 2015-09-09 8:00 GMT+09:00 melanie witt <[email protected]>: > 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. > > 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: [email protected]?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
