Re: [openstack-dev] [api] [docs] Generating API samples
Hi Ken'ichi, Nice idea. On Wed, Aug 26, 2015 at 11:36 AM, Ken'ichi Ohmichi ken1ohmi...@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. 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. Just wondering how we will do that for all microversions as Tempest would not be having tests for all microversions. 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 ken1ohmi...@gmail.com: Hi Anne, 2015-08-25 0:51 GMT+09:00 Anne Gentle annegen...@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-requ...@lists.openstack.org?subject:unsubscribe
Re: [openstack-dev] [api] [docs] Generating API samples
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 ken1ohmi...@gmail.com: Hi Anne, 2015-08-25 0:51 GMT+09:00 Anne Gentle annegen...@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-requ...@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-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [api] [docs] Generating API samples
2015-08-26 12:15 GMT+09:00 GHANSHYAM MANN ghanshyamm...@gmail.com: Hi Ken'ichi, Nice idea. On Wed, Aug 26, 2015 at 11:36 AM, Ken'ichi Ohmichi ken1ohmi...@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 ken1ohmi...@gmail.com: Hi Anne, 2015-08-25 0:51 GMT+09:00 Anne Gentle annegen...@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
Re: [openstack-dev] [api] [docs] Generating API samples
On 08/24/2015 11:51 AM, Anne Gentle wrote: 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? sahara keeps examples for some of it's calls in our repo, although they are not a full example of all calls. these have all been hand-crafted, and could use some updating to add examples for the missing calls. we are currently evaluating a new major version for our api[1], and are talking about creating an api directory in our specs repo to have more up-to-date samples, and a descriptive explanation, of our api. i'm guessing that initially these examples will be hand-crafted. regards, mike [1]: https://review.openstack.org/#/c/212172/ __ 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] [api] [docs] Generating API samples
Hi Anne, 2015-08-25 0:51 GMT+09:00 Anne Gentle annegen...@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-requ...@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-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [api] [docs] Generating API samples
Keystone doesn't use anything similar to sample requests at this time. Though I am sure there wouldn't be much opposition to it provided there was someone stepping up to do the work. Sent via mobile On Aug 24, 2015, at 08:51, Anne Gentle annegen...@justwriteclick.com wrote: 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? Thanks, Anne 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-requ...@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-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
[openstack-dev] [api] [docs] Generating API samples
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? Thanks, Anne 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-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev