Open Stack

Hi Anne,


So it seems that the only remaining issues are:


- using $ref, which is not supported by some upstream tools

- embedding Heat templates in a Swagger doc (not applicable to most OpenStack services)


I responded to the other two in my e-mail to Sean. For the $ref problem, what is the problem with using NPM packages like swagger-tools or swagger-parser [1][2]? They can deference Swagger files into one unified file, which the build tool can then use for HTML rendering. The alternative is to let each project choose whether to use $ref or not. If they do want to spread Swagger docs out into separate documents and reference them, they will need to use a tool in whatever language that works.


I agree that Swagger is a new tool in a new ecosystem, but it definitely solves a lot of our use cases. I think it'd be a lot stronger if we adopted it - at least partially - and contributed our ideas for improvement back upstream.


Was there any cons/disadvantages that I missed which would prevent is incorporating it?


Jamie


[1] https://www.npmjs.com/package/swagger-parser

[2] https://github.com/jamiehannaford/swagger-magnum/blob/master/deref.js


________________________________
From: Anne Gentle <annegentle at justwriteclick.com>
Sent: 17 May 2016 15:35
To: OpenStack Development Mailing List (not for usage questions)
Subject: Re: [openstack-dev] [docs] [api] Swagger limitations?



On Tue, May 17, 2016 at 7:57 AM, Jamie Hannaford <jamie.hannaford at rackspace.com<mailto:jamie.hannaford at rackspace.com>> wrote:

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.


Hi Jamie, thanks for asking. There are a few more limitations/concerns that I'll outline below.


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]


Yes, our first goal is to migrate off of WADL, but that won't prevent use of Swagger, it just means the first priority is to get all projects off of WADL.

I think the details and nuances here were fairly well communicated in the rest of the thread [1] and in the etherpads, but of course that requires a LOT of reading. :)

The main points I'd also like to ensure you know we discussed are [2]:
----
The current Plan of Record is to move to swagger. However this doesn't address a number of key issues:
- swagger is young, most community tools around swagger are 50% - 80% solutions
- swagger provides no facility for nova's 'action' interfaces or microversions

NOTE: actions are used by nova, cinder, manilla, trove, neutron (in extensions) - so 40% of the 12 APIs documented on http://developer.openstack.org/ but only 5 of 19 (26%) REST APIs in OpenStack's governance

NOTE: microversions are used by nova, manilla, ironic, and cinder (and neutron probably in the future unless it proves awful to document and use)

NOTE: while Heat neither uses actions or microversions, it's content templates as inline post requests makes the swagger definition potentially really tough. Not that there shouldn't be full docs for those formats, but they just don't do that today. This same issue will hit other APIs that support post requests of 3rd party content format. Tacker being a good instance.

- the swagger-tools npm package supports $ref, which will clearly be required for maintaining our APIs (autoconverted Nova API is 21KLOC, and probably would be triple that once missing parts are filled in).

NOTE: this is a brand new toolchain that is yet another speed bump in getting people to contribute and maintain, though it is maintained outside of OpenStack
---

Please do consider the additional concerns about $ref and tooling listed above.

In all the communication, I have not prevented the use of Swagger/OpenAPI but I want to make it clear that focused efforts are best for the earliest projects.

- 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).


Agreed. But are we going to solve the microversions display problem once or twice? Right now, I'm focusing on RST + YAML, and microversions need to be solved.

Plus I'd like your thoughts on maintenance of the $ref mechanism and HTML publishing toolchain. We have a patch that lets us build to HTML using npm-provided tooling [3], but I really need to focus on getting a navigation for all OpenStack APIs to be read in a unified way on developer.openstack.org<http://developer.openstack.org> so I haven't tried to make a nice header/footer on that output.

Heh, I see Sean replying also, so I'll go ahead and send. Thanks Jamie.

Anne

1. http://lists.openstack.org/pipermail/openstack-dev/2016-March/090704.html
2. https://etherpad.openstack.org/p/api-site-in-rst
3. https://review.openstack.org/#/c/286659/

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<http://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<mailto:abuse at rackspace.com> and delete the original message. Your cooperation is appreciated.

__________________________________________________________________________
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe<http://OpenStack-dev-request@lists.openstack.org?subject:unsubscribe>
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev




--
Anne Gentle
www.justwriteclick.com<http://www.justwriteclick.com>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20160517/46e67c0f/attachment.html>