[openstack-dev] [docs] [api] Swagger limitations?
jamie.hannaford at rackspace.com
Tue May 17 12:57:22 UTC 2016
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. 
- 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!
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the OpenStack-dev