Open Stack

Some basic questions on editing the REST APIs in openstack/api-site:

ok so I have cloned the api-site git:
i.e. git clone https://github.com/openstack/api-site.git

I have installed maven and done a build
i.e.
sudo apt-get install maven
cd api-site/
mvn clean generate-sources

... and the PDFs and HTML files all build.


Now trying to EDIT files ...

I downloaded a trial copy of Oxygen, and
installed the 'wadl-tools' and 'racbook' addons.



QUESTIONS:
- say I want to update the response of the NOVA list flavor details
- what are the files to edit ? ... and is Oxygen the editor to use even for the wadl files ?

- I tried opening with Oxygen
        ./api-site/api-ref-guides/src/bk-api-ref-compute-v2.xml

- in Author mode,
  Oxygen shows the included file:
       ./api-site/api-ref/src/docbkx/ch_compute-v2.xml

- I go down to ... Section 1.8: Flavors
  Oxygen shows me a wadl resources tag with 3x wadl resource / wadl method tags.
          > with the wadl resource tag
             with a reference to a
             ./api-site/api-ref/src/wadls/compute-api/src/v2/wadl/os-compute-2.wadl#Flavors
          > and the wadl method tag
             with a reference (href) to #listDetailFlavors

??? Oxygen seems to allow you the edit the reference (href) itself.
      But doesn't seem to let you open up this referenced .wadl file thru a context menu.
??? are you supposed to just open the .wadl file with Oxygen manually ???

Assuming yes ...
I can find the resource_type tag for defining the detail flavor list.
which has a method tag with an href to #listDetailFlavors ... in this file.
                SIDE QUESTION: not sure I understand the difference between resources and resource_types in this file ?

I can find the method tag for defining the listDetailFlavor method.
which has a number of subtags for title, request, parameters, json response, xml response ...
The representation tag for documenting (say) the json format has a xsdxt:code with an href to
             ./api-site/api-ref/src/wadls/compute-api/src/v2/api_samples/os-flavor-list-resp.json

??? again, are you supposed to just open the .json file with Oxygen manually and edit ???



apologies for somewhat scattered questions,
I guess the high-level question was that I thought the editing of REST API methods with Oxygen would
be somewhat more WYSIWYG.
Instead of really editing the detailed XML / WADL / JSON files.


Greg.


















-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140825/24af2934/attachment.html>