Open Stack

Hi all,


Back in March Anne wrote a great summary on the current state of Swagger for OpenStack docs: http://lists.openstack.org/pipermail/openstack-dev/2016-March/090659.html.<http://lists.openstack.org/pipermail/openstack-dev/2016-March/090659.html>  Is this still the current state of things? Magnum is looking to document its API soon, so I want to look at the feasibility of doing it in Swagger. If it's not possible, RST should suffice.


In terms of the specific limitations that were listed:


- the /actions endpoint. Would it be possible to use vendor extensions to solve this problem? For example, imagine that you want to document reboot and rebuild operations. You could create custom verb properties for these operations (`x-post-reboot`, `x-post-rebuild`) that would allow differentiation of the JSON payload under the same URL category. The HTML rendering would need to be adapted to take this into consideration. [1]


- microversions. The more I think about it, the more I realise that this is not really a Swagger limitation but more of a consideration that *any* documentation format needs to solve. It seems that per microversion release, a separate doc artefact is required which encapsulates the API at that point in time. This would be very easy to do in Swagger compared to RST (single file vs directory of RST files).


Am I way off here? I would really like to hear others' opinions on this. Thanks for all the great work!


Jamie


[1] https://github.com/OAI/OpenAPI-Specification/blob/master/guidelines/EXTENSIONS.md?


________________________________
Rackspace International GmbH a company registered in the Canton of Zurich, Switzerland (company identification number CH-020.4.047.077-1) whose registered office is at Pfingstweidstrasse 60, 8005 Zurich, Switzerland. Rackspace International GmbH privacy policy can be viewed at www.rackspace.co.uk/legal/swiss-privacy-policy - This e-mail message may contain confidential or privileged information intended for the recipient. Any dissemination, distribution or copying of the enclosed material is prohibited. If you receive this transmission in error, please notify us immediately by e-mail at abuse at rackspace.com and delete the original message. Your cooperation is appreciated.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20160517/4cf2f06c/attachment.html>