settingsLogin | Registersettings

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

0 votes

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


OpenStack Development Mailing List (not for usage questions)
Unsubscribe: OpenStack-dev-request@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
asked Feb 12, 2016 in openstack-docs by annegentle_at_justwr (9,780 points)   2 5 6

1 Response

0 votes

On 02/12/2016 03: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
. 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.

It's the only way we can move around here. :)

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.

K. I'll go review ...

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

This is all super awesome Anne. Thanks for all the great work!


OpenStack Development Mailing List (not for usage questions)
Unsubscribe: OpenStack-dev-request@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
responded Feb 13, 2016 by Monty_Taylor (22,780 points)   2 5 8
...