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:t...@us.ibm.com] > Sent: Friday, May 13, 2016 5:33 AM > To: OpenStack Development Mailing List (not for usage questions) > <openstack-dev@lists.openstack.org> > Cc: Qun XK Wang <bjw...@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.hannaf...@rackspace.com> > To: "OpenStack Development Mailing List (not for usage questions)" > <openstack-dev@lists.openstack.org> > Cc: Qun XK Wang <bjw...@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...@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 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 > > > __________________________________________________________________________ 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
