[openstack-dev] [infra] API docs latest-n-greatest

Alex Xu hejie.xu at intel.com
Fri Aug 21 04:48:44 UTC 2015


> 在 2015年8月21日,上午9:48,Anne Gentle <annegentle at justwriteclick.com> 写道:
> 
> Hi all, 
> A couple of notes for API docs this week. One is, the spec to enable RST builds to developer.openstack.org/api-guide/ <http://developer.openstack.org/api-guide/><service> merged. The plan is completely documented here: 
> http://specs.openstack.org/openstack/docs-specs/specs/liberty/api-site.html <http://specs.openstack.org/openstack/docs-specs/specs/liberty/api-site.html>
> 
> I'm trying to work through the best way to build those while still working with Russell Sim on the WADL to Swagger converter at fairy-slipper:
> https://github.com/russell/fairy-slipper <https://github.com/russell/fairy-slipper>
> 
> Basically run migrate.sh and then run_server.sh to see what Swagger can look like when published (very rough). I'm fixing errors found in the WADL with migrate.sh as we go and hopefully we can start maintaining Swagger only before October. 
> He's working on Issues #4 and #10 but all others are up for grabs: 
> https://github.com/russell/fairy-slipper/issues <https://github.com/russell/fairy-slipper/issues>
> 
> Then, next release we can use our baseline Swagger to ensure the docs get updated either automatically or manually. If your project already uses Pecan you may be able to write Swagger with this https://github.com/elmiko/pecan-swagger <https://github.com/elmiko/pecan-swagger>.
> 
> Some have noted these aren't in the OpenStack git namespace but right now, the publishing outcome is more important than the governance so we'll get there when needed. 
> 
> I'll also put in a formal request here for the infrastructure team to let us know how to request a server that can serve content on developer.openstack.org <http://developer.openstack.org/> rather than Cloud Sites. I'll attend the Infra team meeting next week and I've added it to the agenda.
> https://wiki.openstack.org/wiki/Meetings/InfraTeamMeeting#Agenda_for_next_meeting <https://wiki.openstack.org/wiki/Meetings/InfraTeamMeeting#Agenda_for_next_meeting>
> 
> Final note, I've written a set of API docs guidelines in the API Working Group repository. Please review and offer input, since this guidance applies for all OpenStack APIs. https://review.openstack.org/#/c/214817/ <https://review.openstack.org/#/c/214817/>
> 
> In summary:
>  - Please keep the WADL updated for now and continue to fix WADL bugs.
>  - Take a look at fairy-slipper for the migration and pecan-swagger for generation.
>  - Review the API docs guidelines and ask questions.
>  - With less than 2 months until release, let's git 'er done.

Thanks for the summary!

> 
> Thanks,
> Anne
> 
> -- 
> Anne Gentle
> Rackspace
> 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
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20150821/0a70d540/attachment.html>


More information about the OpenStack-dev mailing list