Open Stack

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:hongbin034 at gmail.com]
> Sent: Saturday, May 14, 2016 4:17 AM
> To: OpenStack Development Mailing List (not for usage questions)
> <openstack-dev at 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-mutou at rf.jp.nec.com
> <mailto: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-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:ton at us.ibm.com <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
> <mailto:openstack-dev at lists.openstack.org> >
> 	> Cc: Qun XK Wang <bjwqun at cn.ibm.com <mailto: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
> <mailto:jamie.hannaford at rackspace.com> >
> 	> To: "OpenStack Development Mailing List (not for usage
> questions)"
> 	> <openstack-dev at lists.openstack.org
> <mailto:openstack-dev at lists.openstack.org> >
> 	> Cc: Qun XK Wang <bjwqun at cn.ibm.com <mailto: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
> <mailto: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/ <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 abuse at rackspace.com
> <mailto: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://OpenStack-dev-request@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://OpenStack-dev-request@lists.openstack.org?subject:unsubscribe>
> 	http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-
> dev
> 
>