Open Stack

Shu,

You mentioned that Swagger was promoted by the API-WG. I wonder if they
mention how to use it. For example, use it to generate the API document,
generate an API client stub, or generate the CLI?

In general, I see Swagger could solve the problem, but it does incur a
significant amount of work. We need to either i) modify the magnum
client/ui to understand the Swagger API spec (the JSON file) or ii) switch
to Swagger-generated client/ui modules. I think Swagger could be a
long-term approach and it needs a POC to show how it works. In short-term,
I would suggest to choose option #1 or #3, or a combination of both.

Best regards,
Hongbin

On Fri, May 13, 2016 at 8:41 AM, Shuu Mutou <shu-mutou at rf.jp.nec.com> wrote:

> Hi peers,
>
> Since Magnum-UI should display selectable values for user, so Magnum-UI
> wants to get available values from API.
> https://blueprints.launchpad.net/magnum/+spec/magnum-api-swagger-support
> https://bugs.launchpad.net/magnum-ui/+bug/1568890
>
> And we don't want to write same things in many files, sometimes with nits.
> ex.) write help messages and available key/values into API, CLI, UI and
> docs
>
> My understanding for Swagger (=OpenAPI) and related tools are:
> - generate swagger-spec JSON file (like YAML file proposed by Ton) from
> source code (with decorator), means writing documents as source code of API
> (#2)
> - provide the JSON file via REST API (#2) to CLI (#1) and UI for available
> values and help messages not inconsistent with the source code.
> - generate online documents from the JSON file (#3)
> - are promoted by API-WG
> - implementations seems starting to be tried in Nova and Zaqar
>
> I'd like to re-propose to use Swagger.
> But it needs more investigation, so I'm not sure where is a middle ground
> for now.
>
>
> Best regards,
>
> Shu Muto
>
> > -----Original Message-----
> > From: Ton Ngo [mailto:ton at us.ibm.com]
> > Sent: Friday, May 13, 2016 5:33 AM
> > To: OpenStack Development Mailing List (not for usage questions)
> > <openstack-dev at lists.openstack.org>
> > Cc: Qun XK Wang <bjwqun at cn.ibm.com>
> > Subject: Re: [openstack-dev] [magnum] How to document 'labels'
> >
> > I would like to add some context for a bigger picture so we might arrive
> > at a more general solution.
> > Typically CLI options are fairly static so the help messages are usually
> > coded directly in the client.
> > This provides a good user experience by making the info readily available
> > to the users.
> > The case for label is a little different, because label provides a
> general
> > mechanism to pass arbitrary key/value pairs.
> > The meaning for these key/value is interpreted based on a particular
> option
> > in a particular COE type, so they are not generally applicable.
> > For instance, Kubernetes baymodel that uses flannel as network-driver
> > supports the label "flannel_backend", with the allowed values of "udp,
> vxlan,
> > host-gw".
> > This particular label would be meaningless in another COE like Mesos.
> >
> > So to provide this kind of info to the users, we have to address 2
> issues:
> >
> > 1.    How the user can discover the available labels specific to the COE,
> > along with the valid values to specify.
> > 2.    How to maintain the help messages specific to each label since they
> > are likely to change frequently.
> >
> >
> > I think just displaying the info for all labels together would not be too
> > helpful.
> > Putting the info in the API would make it available to tools built on
> Magnum,
> > but Madhuri has a good point that the info would not be available when
> the
> > server is not running.
> > We need to accommodate new bay drivers that may add new labels.
> > Validation for the label value is another requirement.
> >
> > Here is a thought on how to meet these requirements: we can install a
> yaml
> > file in /etc/magnum/labels.yaml that would describe all the supported
> > labels, something like:
> >
> > flannel_backend:
> > valid_values:
> > -udp
> > -vxlan
> > -host-gw
> > default_value: udp
> > COE:
> > -kubernetes
> > -swarm
> > help_message: "This label is used with the flannel network driver to
> specify
> > the type of back end to use. The option host-gw gives the best bandwidth
> > performance."
> > doc_url: "http://xxx"
> >
> > Then the client can read this yaml file and list the labels for a COE,
> say
> > Kubernetes. For help on a specific label, the client would print the help
> > message along with the url for further info (if available)
> > The validation code can also load this file for a more general way to
> validate
> > the baymodel, avoiding hardcoding in api/attr_validator.py
> > New bay drivers can just append new labels to this file to have them
> handled
> > in the same way as Magnum supported labels.
> > Optionally, the API server can provide access to this info.
> > In the source, we can keep this file in etc/magnum/labels.yaml.
> > Maintaining the help messages would be simpler since we just need to edit
> > the file.
> >
> > Thought?
> >
> > Ton,
> >
> >
> > Jamie Hannaford ---05/12/2016 07:08:47 AM---+1 for 1 and 3. I'm not sure
> > maintainability should discourage us from exposing information to the u
> >
> > From: Jamie Hannaford <jamie.hannaford at rackspace.com>
> > To: "OpenStack Development Mailing List (not for usage questions)"
> > <openstack-dev at lists.openstack.org>
> > Cc: Qun XK Wang <bjwqun at cn.ibm.com>
> > Date: 05/12/2016 07:08 AM
> > Subject: Re: [openstack-dev] [magnum] How to document 'labels'
> >
> > ________________________________
> >
> >
> >
> >
> > +1 for 1 and 3.
> >
> > I'm not sure maintainability should discourage us from exposing
> information
> > to the user through the client - we'll face the same maintenance burden
> > as we currently do, and IMO it's our job as a team to ensure our docs are
> > up-to-date. Any kind of input which touches the API should also live in
> > the API docs, because that's in line with every other OpenStack service.
> >
> > I don't think I've seen documentation exposed via the API before (#2). I
> > think it's a lot of work too, and I don't see what benefit it provides.
> >
> > Jamie
> >
> >
> > ________________________________
> >
> >
> > From: Hongbin Lu <hongbin.lu at huawei.com>
> > Sent: 11 May 2016 21:52
> > To: OpenStack Development Mailing List (not for usage questions)
> > Cc: Qun XK Wang
> > Subject: [openstack-dev] [magnum] How to document 'labels'
> >
> > Hi all,
> >
> > This is a continued discussion from the last team meeting. For recap,
> ‘labels’
> > is a property in baymodel and is used by users to input additional
> key-pair
> > pairs to configure the bay. In the last team meeting, we discussed what
> > is the best way to document ‘labels’. In general, I heard three options:
> >
> >               1. Place the documentation in Magnum CLI as help text (as
> > Wangqun proposed [1][2]).
> >               2. Place the documentation in Magnum server and expose them
> > via the REST API. Then, have the CLI to load help text of individual
> > properties from Magnum server.
> >               3. Place the documentation in a documentation server (like
> > developer.openstack.org/…), and add the doc link to the CLI help text.
> >
> > For option #1, I think an advantage is that it is close to end-users,
> thus
> > providing a better user experience. In contrast, Tom Cammann pointed out
> > a disadvantage that the CLI help text might be easier to become out of
> date.
> > For option #2, it should work but incurs a lot of extra work. For option
> > #3, the disadvantage is the user experience (since user need to click the
> > link to see the documents) but it makes us easier to maintain. I am
> thinking
> > if it is possible to have a combination of #1 and #3. Thoughts?
> >
> > [1] https://review.openstack.org/#/c/307631/
> > <https://review.openstack.org/#/c/307631/>
> > [2] https://review.openstack.org/#/c/307642/
> > <https://review.openstack.org/#/c/307642/>
> >
> > Best regards,
> > Hongbin
> >
> > ________________________________
> >
> > 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
> >
> >
> >
>
> __________________________________________________________________________
> 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
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20160513/457b6d27/attachment.html>