Open Stack

On 9 September 2015 at 03:43, Anne Gentle <annegentle at justwriteclick.com> wrote:
>
>
> 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.

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