Open Stack

On Mon, Aug 25, 2014 at 1:12 PM, Waines, Greg <Greg.Waines at windriver.com>
wrote:

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

Congrats, you've just passed the first hurdles. Nicely done.


>
>
> 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 ?
>
>
>

Yes.


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

No, as far as I can tell Oxygen (even with wadl-tools installed) does not
know to open WADLs within 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 ???
>
>
>

Yes, I have to choose XML every time I open a WADL file with Oxygen on my
Mac.


>  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 just had that discussion the other day internal to Rackspace, other
writers ask the same thing. Here's all I could come up with, but maybe
someone on this list has more answers. Perhaps it's a useful short-cut at
the top of the WADL that provides "anchor links" to the rest of the long
file. Jorge, any thoughts here?


>
>
> 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 ???
>
>
>

Yes, just edit A bit of history, for Compute those samples were maintained
for v2 in the nova repo itself and tested with code commits, but now they
are only in the api-site repo it looks like. (Yowsa, they were the only
project who ever tested their API samples with each commit, guess that's no
longer the case.)


>
>
>
>
> apologies for somewhat scattered questions,
>

No need, these are good 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.
>
>
Yeah it's really hard isn't it? I'd love to get us to Swagger or RAML with
their nice side-by-side web editors, but this is the current state. Thanks
for asking so nicely and not ranty. :)

Anne


>
>
>
>
> Greg.
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
> _______________________________________________
> Openstack-docs mailing list
> Openstack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140825/0e083980/attachment-0001.html>