Open Stack

2015-08-26 12:15 GMT+09:00 GHANSHYAM MANN <ghanshyammann at gmail.com>:
> Hi Ken'ichi, Nice idea.
>
> On Wed, Aug 26, 2015 at 11:36 AM, Ken'ichi Ohmichi
> <ken1ohmichi at gmail.com> wrote:
>> 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.
>
> And for Project out of Tempest scope can provide tests UUID from their
> Tempest like tests. And doc thing can be served for them via Tempest
> external plugin design.

yeah, +1 for enabling this way for outside-Tempest projects also.

>> 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.
>
> or we can get each param doc string from project via external plugin
> in step 2 along with API generic name
> with assumption that each project should have doc string for each API
> request param.

nice idea, we can make a rule where the script for extracting request params
explanation and use it on step2 :)

> Just wondering how we will do that for all microversions as Tempest
> would not be having tests for all microversions.

Oh, nice point.
I feel it is good to avoid duplicated sample files in Nova if the APIs
are not different between microversions.
We need to implement microversion tests on tempest before anyway.

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
>>>>
>>
>> __________________________________________________________________________
>> 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
>
>
>
> --
> Thanks & Regards
> Ghanshyam Mann
>
> __________________________________________________________________________
> 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