On Tue, May 17, 2016 at 9:51 AM, Jamie Hannaford < jamie.hannaf...@rackspace.com> wrote:
> 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. > > > It's not that these mechanisms are not supported. It's that we don't have assigned development resources to work on Swagger/OpenAPI solutions. In my first reply I sent you a link to an example using OpenStack infrastructure already in place to use npm tooling to build. Please feel free to test with that example: https://review.openstack.org/#/c/286659/ Anne > 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 <annegen...@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.hannaf...@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 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 - 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 ab...@rackspace.com and delete the original >> message. Your cooperation is appreciated. >> >> __________________________________________________________________________ >> OpenStack Development Mailing List (not for usage questions) >> Unsubscribe: >> openstack-dev-requ...@lists.openstack.org?subject:unsubscribe >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev >> >> > > > -- > Anne Gentle > www.justwriteclick.com > > > __________________________________________________________________________ > OpenStack Development Mailing List (not for usage questions) > Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev > > -- Anne Gentle www.justwriteclick.com
__________________________________________________________________________ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev