Open Stack

Hi Chris,

> -----Original Message-----
> From: Christopher Yeoh [mailto:cbkyeoh at gmail.com]
> Sent: Friday, February 07, 2014 8:53 AM
> To: openstack-dev at lists.openstack.org
> Subject: Re: [openstack-dev] [Nova] RFC: Generate API sample files from API schemas
> 
> On Thu, 6 Feb 2014 13:38:22 +0000
> Kenichi Oomichi <oomichi at mxs.nes.nec.co.jp> wrote:
> 
> >
> > Hi,
> >
> > I'd like to propose one idea that autogenerates API sample files from
> > API schema for Nova v3 API.
> >
> > We are working on API validation for v3 API, the works require API
> > schema which is defined with JSONSchema for each API. On the other
> > hand, API sample files of v3 API are autogenerated from the template
> > files of v3 API under nova/tests/integrated/v3/api_samples, as
> > api_samples's README.rst[1]. The API schema files are similar to the
> > template files, because both represent the API parameter structures
> > and each API name.
> >
> > For example, the template file of keypairs is
> > --------------------------------------------------------------------------
> >   {
> >       "keypair": {
> >           "name": "%(keypair_name)s"
> >       }
> >   }
> > --------------------------------------------------------------------------
> >
> > and the API schema file is
> > --------------------------------------------------------------------------
> >   create = {
> >       'type': 'object',
> >       'properties': {
> >           'keypair': {
> >               'type': 'object',
> >               'properties': {
> >                   'name': {
> >                       'type': 'string', 'minLength': 1, 'maxLength':
> > 255, 'pattern': '^[a-zA-Z0-9 _-]+$'
> >                   },
> >                   'public_key': {'type': 'string'},
> >               },
> >               'required': ['name'],
> >               'additionalProperties': False,
> >           },
> >       },
> >       'required': ['keypair'],
> >       'additionalProperties': False,
> >   }
> > --------------------------------------------------------------------------
> >
> > When implementing new v3 API, we need to write/review both files and
> > that would be hard works. For reducing the workload, I'd like to
> > propose one idea[2] that autogenerates API sample files from API
> > schema instead of template files. We would not need to write a
> > template file of a request.
> 
> +1 to automating this. The more the better :-)
> 
> There's probably some details to sort out such as wanting to generate
> multiple template files from the same schema file where parameters are
> optional. Because the generation of the api samples doubles as real
> integration testcases which often pick up issues which the normal
> unittests don't. But I'd love to see these autogenerated (they are a
> bit of pain to create manually).

oh, that is a difficult request, but it is interesting.
I will write it on TODO list in the next patchset.

> Longer term I'd like us to think about how we can use the schema
> files to automate more of the doc generation too (given full Pecan/WSME
> support is likely still a reasonable way off).

Yes, I agree with your idea completely.
It would be nice to autogenarate API specification doc[1].
We could check the API difference between current version and previous one
(Icehouse to Juno) if the above your idea completes. That would be great
for users and developers.

One more idea is that autogenerates API schema files for Tempest's negative
test generator. The negative test generator needs not only request body
definitions but also http-method and url. The API specification doc also
needs bot http-method and url, so it is good to write them on API schema of
API validation.

These ideas are the next steps anyway, I feel:-)


Thanks
Ken'ichi Ohmichi

---
[1]: http://api.openstack.org/api-ref.html