Re: [openstack-dev] [nova] API v2.1 reference documentation

[John Garbutt]

On 9 September 2015 at 03:43, Anne Gentle  wrote:
>
>
> On Tue, Sep 8, 2015 at 8:41 PM, Ken'ichi Ohmichi 
> wrote:
>>
>> Hi Melanie,
>>
>> 2015-09-09 8:00 GMT+09:00 melanie witt :
>> > 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

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [nova] API v2.1 reference documentation

[Ken'ichi Ohmichi]

Hi Melanie,

2015-09-09 8:00 GMT+09:00 melanie witt :
> 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: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [nova] API v2.1 reference documentation

[Anne Gentle]

On Tue, Sep 8, 2015 at 8:41 PM, Ken'ichi Ohmichi 
wrote:

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



-- 
Anne Gentle
Rackspace
Principal Engineer
www.justwriteclick.com
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev