Open Stack

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

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

Chris