Open Stack

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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20160517/898d83ae/attachment.html>