[openstack-dev] [docs] [api] Why WADL when you can Swagger

Anne Gentle annegentle at justwriteclick.com
Thu Mar 10 16:54:42 UTC 2016


On Thu, Mar 10, 2016 at 8:03 AM, Sean Dague <sean at dague.net> wrote:

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

Good question. It's because the migration makes JSON for now, but when I
edit migrated files in http://editor.swagger.io/#/, I import the JSON into
a web-based editor that lets me edit YAML.

The JSON is what's displayed with fairy-slipper but certainly for editing
purposes YAML is preferred. However it's an interesting point about
comments and interchangeability. I'd like a research spike on that.


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

I added you as a reviewer to https://review.openstack.org/#/c/286659/ as
our interim "just give me HTML" replacement while continuing to work on
this spec with the infra team to figure out how to serve HTML built from
fairy-slipper RST and Swagger files.
https://review.openstack.org/#/c/276484/


>
> 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.
>
>
I think we'll need a Swagger file per microversion and then work in the
fairy-slipper UI to make each display. Russell Sim the original
fairy-slipper dev, wanted to work on this but he doesn't have time for this
project any more. Considering how far he brought it, I'm super grateful,
but also we need to apply some more devs to solve the display. Karen
Bradshaw has been working on fairy-slipper and we would all welcome more
developers. Can put that fit-n-finish on until we get infra builds sorted.

Let me know if you have more questions after poking around more, thanks for
asking.

Thanks,
Anne


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



-- 
Anne Gentle
Rackspace
Principal Engineer
www.justwriteclick.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20160310/8b9ac0c0/attachment.html>


More information about the OpenStack-dev mailing list