Hongbin, Actually docs from API-WG is seen in below. [1] http://specs.openstack.org/openstack/api-wg/guidelines/api-docs.html [2] http://docs.openstack.org/contributor-guide/api-guides.html
But since present patches (below) seem to be as PoC or WIP, so we need more time to investigate to use Swagger and related tools. [3] https://bugs.launchpad.net/magnum/+bug/1460161 [4] https://review.openstack.org/#/c/233446/ POC: generate swagger spec from api code base [5] https://review.openstack.org/#/c/286659/ [WIP] Added bootprint and bootprint-swagger to project I agree with you about doing this work as PoC now. At last, I think to use Swagger only for API documentation and providing fixed values, not for generating code. Regards, Shu > -----Original Message----- > From: Hongbin Lu [mailto:hongbin...@gmail.com] > Sent: Saturday, May 14, 2016 4:17 AM > To: OpenStack Development Mailing List (not for usage questions) > <openstack-dev@lists.openstack.org> > Subject: Re: [openstack-dev] [magnum] How to document 'labels' > > 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-mu...@rf.jp.nec.com > <mailto:shu-mu...@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-swagg > er-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 <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 > <mailto:openstack-dev@lists.openstack.org> > > > Cc: Qun XK Wang <bjw...@cn.ibm.com <mailto: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 > <mailto:jamie.hannaf...@rackspace.com> > > > To: "OpenStack Development Mailing List (not for usage > questions)" > > <openstack-dev@lists.openstack.org > <mailto:openstack-dev@lists.openstack.org> > > > Cc: Qun XK Wang <bjw...@cn.ibm.com <mailto: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 > <mailto: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/ <http://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 > <http://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 > <mailto: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://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://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
