<div dir="ltr"><br><div class="gmail_extra"><br><div class="gmail_quote">On Tue, Sep 8, 2015 at 8:41 PM, Ken'ichi Ohmichi <span dir="ltr"><<a href="mailto:ken1ohmichi@gmail.com" target="_blank">ken1ohmichi@gmail.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">Hi Melanie,<br>
<div><div class="h5"><br>
2015-09-09 8:00 GMT+09:00 melanie witt <<a href="mailto:melwittt@gmail.com">melwittt@gmail.com</a>>:<br>
> Hi All,<br>
><br>
> 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.<br>
><br>
> 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.<br>
><br>
> 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.<br></div></div></blockquote><div><br></div><div>They are manual, and Alex made a list of how far behind the 2.1 docs which is in a doc bug here: </div><div><br></div><div><a href="https://bugs.launchpad.net/openstack-api-site/+bug/1488144">https://bugs.launchpad.net/openstack-api-site/+bug/1488144</a><br></div><div> </div><div>It's great to see Atsushi Sakai working hard on those, join him in the patching. </div><div><br></div><div>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.</div><div><br></div><div>Thanks,</div><div>Anne</div><div><br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div><div class="h5">
><br>
> Thanks,<br>
> -melanie (irc: melwitt)<br>
><br>
><br>
> [1] <a href="http://developer.openstack.org/api-ref-compute-v2.1.html" rel="noreferrer" target="_blank">http://developer.openstack.org/api-ref-compute-v2.1.html</a><br>
> [2] <a href="http://developer.openstack.org/api-ref-compute-v2.html" rel="noreferrer" target="_blank">http://developer.openstack.org/api-ref-compute-v2.html</a><br>
<br>
</div></div>Nice point.<br>
"create server" API is most important and necessary to be described on<br>
the document anyway.<br>
<br>
In short-term, we need to describe it from the code by hands, and we<br>
can know available parameters from JSON-Schema code.<br>
The base parameters can be gotten from<br>
<a href="https://github.com/openstack/nova/blob/master/nova/api/openstack/compute/schemas/servers.py#L18" rel="noreferrer" target="_blank">https://github.com/openstack/nova/blob/master/nova/api/openstack/compute/schemas/servers.py#L18</a><br>
In addition, there are extensions which add more parameters and we can<br>
get to know from<br>
<a href="https://github.com/openstack/nova/tree/master/nova/api/openstack/compute/schemas" rel="noreferrer" target="_blank">https://github.com/openstack/nova/tree/master/nova/api/openstack/compute/schemas</a><br>
If module files contain the dict *server_create*, they are also API parameters.<br>
For example, keypairs extension adds "key_name" parameter and we can<br>
know it from <a href="https://github.com/openstack/nova/blob/master/nova/api/openstack/compute/schemas/keypairs.py" rel="noreferrer" target="_blank">https://github.com/openstack/nova/blob/master/nova/api/openstack/compute/schemas/keypairs.py</a><br>
<br>
In long-term, it will be great to generate these API parameter<br>
document from JSON-Schema directly.<br>
JSON-Schema supports "description" parameter and we can describe the<br>
meaning of each parameter.<br>
But that will be long-term way. We need to write them by hands now.<br>
<br>
Thanks<br>
Ken Ohmichi<br>
<br>
__________________________________________________________________________<br>
OpenStack Development Mailing List (not for usage questions)<br>
Unsubscribe: <a href="http://OpenStack-dev-request@lists.openstack.org?subject:unsubscribe" rel="noreferrer" target="_blank">OpenStack-dev-request@lists.openstack.org?subject:unsubscribe</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" rel="noreferrer" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a><br>
</blockquote></div><br><br clear="all"><div><br></div>-- <br><div class="gmail_signature"><div dir="ltr"><div>Anne Gentle</div><div>Rackspace</div><div>Principal Engineer</div><div><a href="http://www.justwriteclick.com" target="_blank">www.justwriteclick.com</a></div></div></div>
</div></div>