Open Stack

Hi Melanie,

2015-09-09 8:00 GMT+09:00 melanie witt <melwittt at 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.
>
> 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