<div dir="ltr">Shu,<div><br></div><div>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?</div><div><br></div><div>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.</div><div><br></div><div>Best regards,</div><div>Hongbin</div></div><div class="gmail_extra"><br><div class="gmail_quote">On Fri, May 13, 2016 at 8:41 AM, Shuu Mutou <span dir="ltr"><<a href="mailto:shu-mutou@rf.jp.nec.com" target="_blank">shu-mutou@rf.jp.nec.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">Hi peers,<br>
<br>
Since Magnum-UI should display selectable values for user, so Magnum-UI wants to get available values from API.<br>
<a href="https://blueprints.launchpad.net/magnum/+spec/magnum-api-swagger-support" rel="noreferrer" target="_blank">https://blueprints.launchpad.net/magnum/+spec/magnum-api-swagger-support</a><br>
<a href="https://bugs.launchpad.net/magnum-ui/+bug/1568890" rel="noreferrer" target="_blank">https://bugs.launchpad.net/magnum-ui/+bug/1568890</a><br>
<br>
And we don't want to write same things in many files, sometimes with nits.<br>
ex.) write help messages and available key/values into API, CLI, UI and docs<br>
<br>
My understanding for Swagger (=OpenAPI) and related tools are:<br>
- 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)<br>
- 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.<br>
- generate online documents from the JSON file (#3)<br>
- are promoted by API-WG<br>
- implementations seems starting to be tried in Nova and Zaqar<br>
<br>
I'd like to re-propose to use Swagger.<br>
But it needs more investigation, so I'm not sure where is a middle ground for now.<br>
<br>
<br>
Best regards,<br>
<br>
Shu Muto<br>
<span class=""><br>
> -----Original Message-----<br>
> From: Ton Ngo [mailto:<a href="mailto:ton@us.ibm.com">ton@us.ibm.com</a>]<br>
> Sent: Friday, May 13, 2016 5:33 AM<br>
> To: OpenStack Development Mailing List (not for usage questions)<br>
> <<a href="mailto:openstack-dev@lists.openstack.org">openstack-dev@lists.openstack.org</a>><br>
> Cc: Qun XK Wang <<a href="mailto:bjwqun@cn.ibm.com">bjwqun@cn.ibm.com</a>><br>
</span><span class="">> Subject: Re: [openstack-dev] [magnum] How to document 'labels'<br>
><br>
</span><span class="">> I would like to add some context for a bigger picture so we might arrive<br>
> at a more general solution.<br>
> Typically CLI options are fairly static so the help messages are usually<br>
> coded directly in the client.<br>
> This provides a good user experience by making the info readily available<br>
> to the users.<br>
> The case for label is a little different, because label provides a general<br>
> mechanism to pass arbitrary key/value pairs.<br>
> The meaning for these key/value is interpreted based on a particular option<br>
> in a particular COE type, so they are not generally applicable.<br>
> For instance, Kubernetes baymodel that uses flannel as network-driver<br>
> supports the label "flannel_backend", with the allowed values of "udp, vxlan,<br>
> host-gw".<br>
> This particular label would be meaningless in another COE like Mesos.<br>
><br>
> So to provide this kind of info to the users, we have to address 2 issues:<br>
><br>
</span>> 1. How the user can discover the available labels specific to the COE,<br>
<span class="">> along with the valid values to specify.<br>
</span>> 2. How to maintain the help messages specific to each label since they<br>
<div class="HOEnZb"><div class="h5">> are likely to change frequently.<br>
><br>
><br>
> I think just displaying the info for all labels together would not be too<br>
> helpful.<br>
> Putting the info in the API would make it available to tools built on Magnum,<br>
> but Madhuri has a good point that the info would not be available when the<br>
> server is not running.<br>
> We need to accommodate new bay drivers that may add new labels.<br>
> Validation for the label value is another requirement.<br>
><br>
> Here is a thought on how to meet these requirements: we can install a yaml<br>
> file in /etc/magnum/labels.yaml that would describe all the supported<br>
> labels, something like:<br>
><br>
> flannel_backend:<br>
> valid_values:<br>
> -udp<br>
> -vxlan<br>
> -host-gw<br>
> default_value: udp<br>
> COE:<br>
> -kubernetes<br>
> -swarm<br>
> help_message: "This label is used with the flannel network driver to specify<br>
> the type of back end to use. The option host-gw gives the best bandwidth<br>
> performance."<br>
> doc_url: "<a href="http://xxx" rel="noreferrer" target="_blank">http://xxx</a>"<br>
><br>
> Then the client can read this yaml file and list the labels for a COE, say<br>
> Kubernetes. For help on a specific label, the client would print the help<br>
> message along with the url for further info (if available)<br>
> The validation code can also load this file for a more general way to validate<br>
> the baymodel, avoiding hardcoding in api/attr_validator.py<br>
> New bay drivers can just append new labels to this file to have them handled<br>
> in the same way as Magnum supported labels.<br>
> Optionally, the API server can provide access to this info.<br>
> In the source, we can keep this file in etc/magnum/labels.yaml.<br>
> Maintaining the help messages would be simpler since we just need to edit<br>
> the file.<br>
><br>
> Thought?<br>
><br>
> Ton,<br>
><br>
><br>
</div></div><div class="HOEnZb"><div class="h5">> Jamie Hannaford ---05/12/2016 07:08:47 AM---+1 for 1 and 3. I'm not sure<br>
> maintainability should discourage us from exposing information to the u<br>
><br>
> From: Jamie Hannaford <<a href="mailto:jamie.hannaford@rackspace.com">jamie.hannaford@rackspace.com</a>><br>
> To: "OpenStack Development Mailing List (not for usage questions)"<br>
> <<a href="mailto:openstack-dev@lists.openstack.org">openstack-dev@lists.openstack.org</a>><br>
> Cc: Qun XK Wang <<a href="mailto:bjwqun@cn.ibm.com">bjwqun@cn.ibm.com</a>><br>
> Date: 05/12/2016 07:08 AM<br>
> Subject: Re: [openstack-dev] [magnum] How to document 'labels'<br>
><br>
> ________________________________<br>
><br>
><br>
><br>
><br>
> +1 for 1 and 3.<br>
><br>
> I'm not sure maintainability should discourage us from exposing information<br>
> to the user through the client - we'll face the same maintenance burden<br>
> as we currently do, and IMO it's our job as a team to ensure our docs are<br>
> up-to-date. Any kind of input which touches the API should also live in<br>
> the API docs, because that's in line with every other OpenStack service.<br>
><br>
> I don't think I've seen documentation exposed via the API before (#2). I<br>
> think it's a lot of work too, and I don't see what benefit it provides.<br>
><br>
> Jamie<br>
><br>
><br>
> ________________________________<br>
><br>
><br>
> From: Hongbin Lu <<a href="mailto:hongbin.lu@huawei.com">hongbin.lu@huawei.com</a>><br>
> Sent: 11 May 2016 21:52<br>
> To: OpenStack Development Mailing List (not for usage questions)<br>
> Cc: Qun XK Wang<br>
> Subject: [openstack-dev] [magnum] How to document 'labels'<br>
><br>
> Hi all,<br>
><br>
> This is a continued discussion from the last team meeting. For recap, ‘labels’<br>
> is a property in baymodel and is used by users to input additional key-pair<br>
> pairs to configure the bay. In the last team meeting, we discussed what<br>
> is the best way to document ‘labels’. In general, I heard three options:<br>
><br>
> 1. Place the documentation in Magnum CLI as help text (as<br>
> Wangqun proposed [1][2]).<br>
> 2. Place the documentation in Magnum server and expose them<br>
> via the REST API. Then, have the CLI to load help text of individual<br>
> properties from Magnum server.<br>
> 3. Place the documentation in a documentation server (like<br>
> <a href="http://developer.openstack.org/" rel="noreferrer" target="_blank">developer.openstack.org/</a>…), and add the doc link to the CLI help text.<br>
><br>
> For option #1, I think an advantage is that it is close to end-users, thus<br>
> providing a better user experience. In contrast, Tom Cammann pointed out<br>
> a disadvantage that the CLI help text might be easier to become out of date.<br>
> For option #2, it should work but incurs a lot of extra work. For option<br>
> #3, the disadvantage is the user experience (since user need to click the<br>
> link to see the documents) but it makes us easier to maintain. I am thinking<br>
> if it is possible to have a combination of #1 and #3. Thoughts?<br>
><br>
> [1] <a href="https://review.openstack.org/#/c/307631/" rel="noreferrer" target="_blank">https://review.openstack.org/#/c/307631/</a><br>
> <<a href="https://review.openstack.org/#/c/307631/" rel="noreferrer" target="_blank">https://review.openstack.org/#/c/307631/</a>><br>
> [2] <a href="https://review.openstack.org/#/c/307642/" rel="noreferrer" target="_blank">https://review.openstack.org/#/c/307642/</a><br>
> <<a href="https://review.openstack.org/#/c/307642/" rel="noreferrer" target="_blank">https://review.openstack.org/#/c/307642/</a>><br>
><br>
> Best regards,<br>
> Hongbin<br>
><br>
> ________________________________<br>
><br>
> Rackspace International GmbH a company registered in the Canton of Zurich,<br>
> Switzerland (company identification number CH-020.4.047.077-1) whose<br>
> registered office is at Pfingstweidstrasse 60, 8005 Zurich, Switzerland.<br>
> Rackspace International GmbH privacy policy can be viewed at<br>
> <a href="http://www.rackspace.co.uk/legal/swiss-privacy-policy" rel="noreferrer" target="_blank">www.rackspace.co.uk/legal/swiss-privacy-policy</a> - This e-mail message may<br>
> contain confidential or privileged information intended for the recipient.<br>
> Any dissemination, distribution or copying of the enclosed material is<br>
> prohibited. If you receive this transmission in error, please notify us<br>
> immediately by e-mail at <a href="mailto:abuse@rackspace.com">abuse@rackspace.com</a> and delete the original<br>
> message. Your cooperation is appreciated.<br>
> ______________________________________________________________________<br>
> ____<br>
> OpenStack Development Mailing List (not for usage questions)<br>
> Unsubscribe:<br>
> <a href="http://OpenStack-dev-request@lists.openstack.org?subject:unsubscribe" rel="noreferrer" target="_blank">OpenStack-dev-request@lists.openstack.org?subject:unsubscribe</a><br>
> <a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" rel="noreferrer" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a><br>
><br>
><br>
><br>
<br>
__________________________________________________________________________<br>
OpenStack Development Mailing List (not for usage questions)<br>
Unsubscribe: <a href="http://OpenStack-dev-request@lists.openstack.org?subject:unsubscribe" rel="noreferrer" target="_blank">OpenStack-dev-request@lists.openstack.org?subject:unsubscribe</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" rel="noreferrer" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a><br>
</div></div></blockquote></div><br></div>