[openstack-dev] [docs] [api] Why WADL when you can Swagger
sean at dague.net
Thu Mar 10 14:03:42 UTC 2016
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 -
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
> 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:
> Why are we doing all this?
> The overall vision is still intact in the original specifications
> , 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.
> 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:
> 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:
> Anne Gentle
> Principal Engineer
> www.justwriteclick.com <http://www.justwriteclick.com>
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
More information about the OpenStack-dev