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: [email protected]?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: [email protected]?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
