Open Stack

On Tue, May 17, 2016 at 9:51 AM, Jamie Hannaford <
jamie.hannaford at 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 <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> 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 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://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-request at lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
>


-- 
Anne Gentle
www.justwriteclick.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20160517/98f36144/attachment-0001.html>