Open Stack

Ok, I'm responding very late to this thread because other bits of the
release cycle had attention.

A couple of questions.

1) why are we using the JSON version of the specification instead of the
YAML one -
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#format

One of the reasons this is a bit of a hot button issue for me is beyond
YAML being a bit more readable, it allows *comments* in the file. The
lack of comments support in JSON makes it really problematic to do
anything except completely obvious things that will only ever be
consumed by a computer. Some of these APIs are big, and being able to
provide annotations to API spec developers is really important.

2) What is the tox target I can use to build the HTML out of swagger for
a single project? So that we can iterate here.

3) What is the current best thinking about microversion specification.

This is the #1 current issue with our API reference site, as we've now
got 3 (and soon 4) APIs doing this, but 0 support on the API site to
display this information. If we don't have a near term path forward I
think we're going to just have to dump all the tools and just go to
editing the HTML directly.



On 02/12/2016 04:45 PM, Anne Gentle wrote:
> Hi all,
> I wanted to give an update on the efforts to provide improved
> application developer information on developer.openstack.org
> <http://developer.openstack.org>. Wrangling this much valuable
> information and gathering it in a way that helps people is no simple
> matter. So. We move forward one step at a time.
> 
> What's new?
> ----------------
> This week, with every build of the api-site, we are now running
> fairy-slipper to migrate from WADL to Swagger for API reference
> information. Those migrated Swagger files are then copied to
> developer.openstack.org/draft/swagger
> <http://developer.openstack.org/draft/swagger>.
> 
> We know that not all files migrate smoothly. We'd love to get teams
> looking at these migrated files. Thank you to those of you already
> submitting fixes!
> 
> In addition, the infra team is reviewing a spec now so that we can serve
> API reference information from the developer.openstack.org
> <http://developer.openstack.org> site:
> https://review.openstack.org/#/c/276484/
> 
> Why are we doing all this?
> ----------------------------------
> The overall vision is still intact in the original specifications
> [1][2], however we need to do a lot of web design and front end work to
> get where we want to be.
> 
> What can I do?
> --------------------
> Check out these Swagger files.
> http://developer.openstack.org/draft/swagger/blockstorage-v1-swagger.json
> http://developer.openstack.org/draft/swagger/blockstorage-v2-swagger.json
> http://developer.openstack.org/draft/swagger/clustering-v1-swagger.json
> http://developer.openstack.org/draft/swagger/compute-v2.1-swagger.json
> http://developer.openstack.org/draft/swagger/data-processing-v1.1-swagger.json
> http://developer.openstack.org/draft/swagger/database-v1-swagger.json
> http://developer.openstack.org/draft/swagger/identity-admin-v2-swagger.json
> http://developer.openstack.org/draft/swagger/identity-extensions-v2-swagger.json
> http://developer.openstack.org/draft/swagger/identity-extensions-v3-swagger.json
> http://developer.openstack.org/draft/swagger/identity-v2-swagger.json
> http://developer.openstack.org/draft/swagger/identity-v3-swagger.json
> http://developer.openstack.org/draft/swagger/image-v1-swagger.json
> http://developer.openstack.org/draft/swagger/networking-extensions-v2-swagger.json
> http://developer.openstack.org/draft/swagger/networking-v2-swagger.json
> http://developer.openstack.org/draft/swagger/objectstorage-v1-swagger.json
> http://developer.openstack.org/draft/swagger/orchestration-v1-swagger.json
> http://developer.openstack.org/draft/swagger/share-v1-swagger.json
> http://developer.openstack.org/draft/swagger/telemetry-v2-swagger.json
> 
> If you see a problem in the original WADL, log it here:
> https://bugs.launchpad.net/openstack-api-site. If you see a problem with
> the migration tool, log it here:
> https://bugs.launchpad.net/openstack-doc-tools.
> 
> When will the work be completed?
> --------------------------------------------
> 
> I had hoped to have more to show by this point, but I await the infra
> team's review of the server spec above, and we continue to work on the
> bugs in the migration and output. Once the server spec work is complete,
> we can release the draft site.
> 
> What if I have more questions?
> ------------------------------------------
> You can always hop onto #openstack-doc or #openstack-sdks to ask me or
> another API working group member for guidance.
> 
> Last but not least, if you want to learn more about Swagger in the
> upstream contributors track at the Summit, vote for this session:
> https://www.openstack.org/summit/austin-2016/vote-for-speakers/presentation/7723
> 
> Thanks,
> Anne
> 
> --
> Anne Gentle
> Rackspace
> Principal Engineer
> www.justwriteclick.com <http://www.justwriteclick.com>
> 
> 1.
> http://specs.openstack.org/openstack/docs-specs/specs/mitaka/app-guides-mitaka-vision.html
> 2.
> http://specs.openstack.org/openstack/docs-specs/specs/liberty/api-site.html
> 
> 
> __________________________________________________________________________
> 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
> 


-- 
Sean Dague
http://dague.net