Open Stack

Hi Anne, Nova API guys,

I'd like to explain how to generate API docs from Tempest log.

In Tempest, each API test contains UUID for the test identification now.
Current my idea is to parse tempest log, create a patch based on the
parsing and post a patch to each project repo like:

1. Each project like Nova
  Contain the combinations of both generic API name("create a server",
etc.) and test UUID of Tempest
2. Tempest
  * Output test UUIDs to Tempest log for each API operation
  * Contain **Script A** to parse Tempest log for getting URL,
headers, request body, response body and normal status code based on
the specified test UUID
  * Contain **Script B** to get the above combinations from each
project repo via external plugin interfaces[1], run **Script A** with
each test UUID and create API samples for each generic API name.
3. Bot of openstack-infra
  * Create an API sample patch for each project and post it if the
sample doesn't exist in the repo.

Even after this way is implemented, the descriptions of request
parameters are not covered on api docs:
But each project will be able to get them with each project own way
like Pecan/WSME docstring, JSON-Schema or by hands.

Any thought?

Thanks
Ken Ohmichi
---
[1]: http://specs.openstack.org/openstack/qa-specs/specs/tempest-external-plugin-interface.html

2015-08-26 10:36 GMT+09:00 Ken'ichi Ohmichi <ken1ohmichi at gmail.com>:
> Hi Anne,
>
> 2015-08-25 0:51 GMT+09:00 Anne Gentle <annegentle at justwriteclick.com>:
>> Hi all,
>>
>> I'm writing to find out how teams keep API sample requests and responses
>> up-to-date. I know the nova team has a sample generator [1] that they've
>> maintained for a few years now. Do other teams have something similar? If
>> so, is your approach like the nova one?
>
> We had a weekly IRC meeting of Nova API yesterday(today for some
> guys), and we discussed how to generate/maintain API docs in long
> term.
> After the discussion, I have an idea.
>
> How about generating API sample files from Tempest log files?
>
> Now Tempest is writing most necessary parts of API docs((URL, headers,
> request body, response body, http status code) to its own log file
> like:
>
> http://logs.openstack.org/88/207688/3/check/gate-tempest-dsvm-full/d7a79d1/logs/tempest.txt.gz#_2015-08-10_13_20_36_982
>
> 2015-08-10 13:20:36.982 [..] 202 POST
> http://127.0.0.1:8774/v2/c2ab3e6ac69e43bb925a4895075e47d7/servers
> 0.920s
> 2015-08-10 13:20:36.983 [..] Request - Headers: {'Content-Type':
> 'application/json', 'X-Auth-Token': '<omitted>', 'Accept':
> 'application/json'}
>         Body: {"server": {"name":
> "tempest.common.compute-instance-607936499", "networks": [{"uuid":
> "e63068c6-99d5-41f5-804d-ccb812bfeb51"}], "imageRef":
> "d4159c59-cbfb-43f1-94de-3552d1f2871e", "flavorRef": "42"}}
>     Response - Headers: {'location':
> 'http://127.0.0.1:8774/v2/c2ab3e6ac69e43bb925a4895075e47d7/servers/19f98a6f-26d2-4491-93a8-8e894f19034c',
> 'content-type': 'application/json', 'date': 'Mon, 10 Aug 2015 13:20:36
> GMT', 'x-compute-request-id':
> 'req-0fa22034-c1d5-41b2-bfb9-6de533733290', 'connection': 'close',
> 'status': '202', 'content-length': '434'}
>         Body: {"server": {"security_groups": [{"name": "default"}],
> "OS-DCF:diskConfig": "MANUAL", "id":
> "19f98a6f-26d2-4491-93a8-8e894f19034c", "links": [{"href":
> "http://127.0.0.1:8774/v2/c2ab3e6ac69e43bb925a4895075e47d7/servers/19f98a6f-26d2-4491-93a8-8e894f19034c",
> "rel": "self"}, {"href":
> "http://127.0.0.1:8774/c2ab3e6ac69e43bb925a4895075e47d7/servers/19f98a6f-26d2-4491-93a8-8e894f19034c",
> "rel": "bookmark"}], "adminPass": "2iEDo2EP5wRM"}} _log_request_full
> /opt/stack/new/tempest/.tox/full/local/lib/python2.7/site-packages/tempest_lib/common/rest_client.py:411
>
> I feel it is difficult to implement the similar sample test way of
> Nova on each project.
> The above Tempest log is written on tempest-lib side and that is
> common way between projects.
> So we can use this way for all projects as a common/consistent way, I
> imagine now.
>
> I will make/write the detail of this idea later.
>
> Thanks
> Ken Ohmichi
>
> ---
>
>> 1.
>> https://github.com/openstack/nova/blob/master/nova/tests/functional/api_sample_tests/api_sample_base.py
>>
>> --
>> Anne Gentle
>> Rackspace
>> Principal Engineer
>> www.justwriteclick.com
>>
>> __________________________________________________________________________
>> 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
>>