Open Stack

On Tue, Sep 8, 2015 at 8:41 PM, Ken'ichi Ohmichi <ken1ohmichi at gmail.com>
wrote:

> 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.
>

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.

Thanks,
Anne

>
> > 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-request at lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>



-- 
Anne Gentle
Rackspace
Principal Engineer
www.justwriteclick.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20150908/7ad02a9f/attachment.html>