Open Stack

On 14 July 2015 at 03:45, Anne Gentle <annegentle at justwriteclick.com> wrote:
>
>
> So I know it doesn't look like I've been doing anything but I have been
> trying to figure out JSON schema and fairy-slipper. :) I also went ahead
> and merged the spec since we have a good plan and can update it as needed
> from here on.
>

Good stuff,  I have literally been doing nothing for the past week.

Current status:
- reasonably complete RST description of the API.  I think that the only
thing not being translated is some of the formatting (numbered list for
example) http://fairy-slipper.russellsim.org/rst/
- prototype webserver but it doesn't render to JSON all the attributes that
are needed.


> For one task, which is creating a JSON Schema we can use to validate the
> output, I think I need to study this line:
>
> https://github.com/russell/fairy-slipper/blob/master/tools/wadl_to_swagger.py#L448
>

One unfortunate thing that has happened during the course of development is
that I have had to compromise on the contents of the intermediate Swagger
file.  As I started to develop the RST files i found that i needed other
data to be included to make generation easier.  As a result the current
Swagger files include more changes than I have described previously.

Yes we should be able to take the upstream swagger schema and modify it to
include all the changes i described in that other email,  if you can do
that I should be able to write a functional test that validates the output
of the webserver against it.  That would be really helpful.  At the moment
I have zero tests, it's sad :(


That line you have identified basically adds reference to an embedded
JSONSchema description that will be located in the definitions section
(JSON object key) of the Swagger file, it's a normal part of swagger.  It's
always add but not always used.  In the case where there is no schema I
trim this element,  this happens when converting to RST.

But 3 lines above is the 'method' key, this is new.  The list stuff is
stored in a local dict on the class called self.apis it is keyed to the
URLs and the value is [ ] and extended gradually as new self.current_api
objects are created.
https://github.com/russell/fairy-slipper/blob/master/tools/wadl_to_swagger.py#L473

https://github.com/russell/fairy-slipper/blob/master/tools/wadl_to_swagger.py#L438

then write a JSON Schema file that is identical to the Swagger 2.0 spec
> except for allowing an array for GET and POST and then moving the
> resources. Is that correct? Should I do a PR to the fairy-slipper repo with
> a JSON Schema file? I was thinking I'd put it in /tools then we can
> validate against it if needed.
>
> Also I attended the nova team's API meeting last week and they are excited
> to help.
>

Yes!  That would be great!  I'm going to squash the current commits and
start using proper commit messages tonight.  Just push when ever you like.


> I am curious about how the migration will work:
>> When this is proposed as a patch will we delete the WADL files
>> immediately?  or will they hang around?
>>
>
> I'd love to delete the WADL files as a patch that depends on the patch
> that replaces it all. They'll be retrievable in the git log if we ever need
> them "one day." I'm good with that.
>

>
>> Perhaps we could use a feature branch?  That way the OPs team can have a
>> chance to prep the openstack.org website for the transition and we can
>> maintain the WADL files until we are ready to launch?
>>
>
> A feature branch is exactly what we can do (or the dependent branch I
> mentioned above).
>
> I was targeting developer.openstack.org for the content, and the current
> job is a file copy through FTP. So to prepare developer.openstack.org I
> guess we'll need the web server ready? It's currently Cloud Sites on
> Rackspace if my memory serves. We'll need to get a real web server. Can you
> describe the specs, as in, what would the implementation require? We'd
> probably need to puppet-ize the build? Hopefully Infra-team can offer us
> input.
>

Cool,  Currently it's hosted on the smallest VM that Rackspace offers.  I'm
still working on getting the webserver into a state where it can replace
the static files, once that is done we can look making a puppet module.


> What are we going to do about the frontend?  That is an area that will
>> require some thought about how to present the information.  I personally
>> don't like either example above.  I don't like the current API doc, too
>> much scrolling, no navigation.  jensoleg's is crap because of too much
>> scrolling, also features confusing amounts of scrolling for large response
>> examples.  The default swagger interface sucks because it assumes I am a
>> robot?  why is the URL more important that what the URL does?  Basically i
>> think we can do better.  I think this is probably the best interface for
>> API documentation i have seen so far http://docs.apimatic.apiary.io/ but
>> if people can suggest other sites we can draw ideas from that would be
>> great.
>>
>
> Agreed on the large response examples from jensoleg's Stripe example but I
> like the side-by-side (and Apiary does something similar). At Rackspace we
> are working on new layouts as well, so maybe we could work together on
> interfaces, let me know and I'll connect you.
>
>
Yep,  once I get the webserver off the ground.  I'll start creating a
layout,  I'm guessing that it will probably be a mix of all the layouts
listed above.  But it will not allow the size of the examples to affect the
page scroll.  I do like the 3 column layout though.  I'll see what I can
prototype and then I'll have a look at the new Rackspace doc layout.

-- 
Cheers,
Russell Sim
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20150714/e917439e/attachment-0001.html>