[OpenStack-docs] [docs] [api] Why WADL when you can Swagger

Anne Gentle annegentle at justwriteclick.com
Fri Feb 12 21:45:11 UTC 2016


Hi all,
I wanted to give an update on the efforts to provide improved application
developer information on 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.

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

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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20160212/79b8b080/attachment.html>


More information about the OpenStack-docs mailing list