<div dir="ltr"><div class="gmail_extra"><br><div class="gmail_quote">On 29 June 2015 at 23:03, Karen Bradshaw <span dir="ltr"><<a href="mailto:kbhawkey@gmail.com" target="_blank">kbhawkey@gmail.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div dir="ltr" style="font-size:12.8000001907349px">Hi, Russell. I just started to look at this code but thought of a few questions,<div>1) How did you validate the generated swagger-json files?</div></div></blockquote><div><br></div><div>So there is no validation performed on the swagger, at the moment I'm relying on visual validation to make sure that all the data is converted. There is a lot of different functionality that is being used in the WADL/DocBook files, I've tried to accommodate it all but who knows.</div><div><br></div><div>In saying that, I'm relatively confident that most if not all thing are either translated, or are at least listed in the map dictionaries at the top of the .py files.</div><div><br></div><div>This means that there are probably things that are missing, or incorrectly migrated. In saying that the generate rst files are quite good at showing the gaps.</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div dir="ltr" style="font-size:12.8000001907349px"><div>2) Did you create a new schema, Swagger 2.0-OpenStack? What </div><div>does it look like?</div></div></blockquote><div><br></div><div>Yes.</div><div><br></div><div>So there are 3 modifications that we are currently using.</div><div><br></div><div>1. Swagger doesn't support request examples.</div><div><br></div><div>So that was added today. I'm still using the operation objects [0] but with an extra field called examples which contains an example object [1].</div><div><br></div><div>2. Swagger doesn't support multiple duplicate operations (get/put/post/delete/head) at the same url</div><div><br></div><div>This is exactly what the actions section from one of the previous emails was talking about with either the heat actions or nova server actions [3]</div><div><br></div><div>Basically this is a big no-no in REST, so swagger outright doesn't support it.</div><div><br></div><div>This is a little more complicated to explain so I'll use example code. But basically we are converting what was a JSON object to a JSON array and moving the method (get/post/put/head) to the inner JSON object. This allows us to have several operations all with the POST method (required for the actions schema)</div><div><br></div><div><p style="margin-top:0px;margin-bottom:0px;padding-top:0.5em;padding-bottom:0.5em;color:rgb(0,0,0);font-family:sans-serif">e.g. normal swagger</p><p style="margin-top:0px;margin-bottom:0px;padding-top:0.5em;padding-bottom:0.5em;color:rgb(0,0,0);font-family:sans-serif"><span class="" style="white-space:pre;font-family:'Lucida Console','Lucida Sans Typewriter',Monaco,monospace"> {</span><br><span class="" style="white-space:pre;font-family:'Lucida Console','Lucida Sans Typewriter',Monaco,monospace"> "paths": {</span><br><span class="" style="white-space:pre;font-family:'Lucida Console','Lucida Sans Typewriter',Monaco,monospace"> "/v2/{tenant_id}/servers/{server_id}/action": {</span><br><span class="" style="white-space:pre;font-family:'Lucida Console','Lucida Sans Typewriter',Monaco,monospace"> "get": {</span><br><span class="" style="white-space:pre;font-family:'Lucida Console','Lucida Sans Typewriter',Monaco,monospace"> "responses": {</span><br><span class="" style="white-space:pre;font-family:'Lucida Console','Lucida Sans Typewriter',Monaco,monospace"> "200": {</span></p><p style="margin-top:0px;margin-bottom:0px;padding-top:0.5em;padding-bottom:0.5em;color:rgb(0,0,0)"><span class="" style="white-space:pre"><font face="arial, helvetica, sans-serif">our swagger</font></span></p><p style="margin-top:0px;margin-bottom:0px;padding-top:0.5em;padding-bottom:0.5em;color:rgb(0,0,0);font-family:sans-serif"><span class="" style="white-space:pre;font-family:'Lucida Console','Lucida Sans Typewriter',Monaco,monospace"> {</span><br><span class="" style="white-space:pre;font-family:'Lucida Console','Lucida Sans Typewriter',Monaco,monospace"> "paths": {</span><br><span class="" style="white-space:pre;font-family:'Lucida Console','Lucida Sans Typewriter',Monaco,monospace"> "/v2/{tenant_id}/servers/{server_id}/action": [</span><br><span class="" style="white-space:pre;font-family:'Lucida Console','Lucida Sans Typewriter',Monaco,monospace"> {</span><span class="" style="white-space:pre;font-family:'Lucida Console','Lucida Sans Typewriter',Monaco,monospace">"method": "get",</span><br><span class="" style="white-space:pre;font-family:'Lucida Console','Lucida Sans Typewriter',Monaco,monospace"> "responses": {</span><br><span class="" style="white-space:pre;font-family:'Lucida Console','Lucida Sans Typewriter',Monaco,monospace"> "200": {</span></p></div><div><br></div><div>3. Swagger doesn't support extended documentation of Tags.</div><div><br></div><div>Put simply Tags are used group the API calls. So all the folding bits in the demo at [4].</div><div><br></div><div>They only support the single line of text. So for the Tag <span style="color:rgb(0,0,0);font-family:arial,helvetica,sans-serif;line-height:inherit">image-metadata, the Tag's description is </span><span style="color:rgb(0,0,0);font-family:arial,helvetica,sans-serif;line-height:inherit"> "Image metadata" [5].</span></div><div><font color="#000000" face="arial, helvetica, sans-serif"><br></font></div><div><font color="#000000" face="arial, helvetica, sans-serif">At the moment I'm putting the actual documentation we currently have for say server create [6] into the swagger under the key summary (this was a poor choice, will change tomorrow)</font></div><div><font color="#000000" face="arial, helvetica, sans-serif"><br></font></div><div><font color="#000000" face="arial, helvetica, sans-serif">This extended documentation makes it's way into the ReST files [7] but currently the Swagger-UI we are using doesn't display it.<br></font></div><div><font color="#000000" face="arial, helvetica, sans-serif"><br></font></div><div><font color="#000000" face="arial, helvetica, sans-serif">NB, I did spot the conversion issues :(</font></div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div dir="ltr" style="font-size:12.8000001907349px"><div>3) Can you elaborate a bit more about the tagging system?</div></div></blockquote></div><br>So, the tagging system works like this.</div><div class="gmail_extra"><br></div><div class="gmail_extra">Each REST endpoint/method (swagger calls them operations) e.g. POS<font face="arial, helvetica, sans-serif" color="#000000">T <span style="line-height:20px">{tenant_id}/servers</span>.</font> Has any number of tags assigned to it. That endpoint/method object will then appear under each Tag or under a magic tag default if it has none.</div><div class="gmail_extra"><br></div><div class="gmail_extra">So for example, we may have a call like compute server metadata [8] which we would like to appear in both the servers section and the metadata section. Easy, we just tag it with both. I'm sure you could do the same with WADL, but at the same time we do have options to provide filtering and other things here because the UI will be client side. So we can continue to group the endpoint/methods like we have in the WADL, but we could also include extra tags that are hidden and only used for searching/filtering or they can be used to ferry extra documentation about methods with that tag.</div><div class="gmail_extra"><br></div><div class="gmail_extra">0. <a href="http://swagger.io/specification/#operationObject">http://swagger.io/specification/#operationObject</a> <br><div>1. <a href="http://swagger.io/specification/#exampleObject">http://swagger.io/specification/#exampleObject</a></div><div>2. <a href="http://developer.openstack.org/api-ref-compute-v2.html#compute_server-actions">http://developer.openstack.org/api-ref-compute-v2.html#compute_server-actions</a></div><div>4. <a href="http://fairy-slipper.russellsim.org/swagger-ui/">http://fairy-slipper.russellsim.org/swagger-ui/</a></div><div>5. <span style="color:rgb(0,0,0);font-family:arial,helvetica,sans-serif"><a href="http://swagger.io/specification/#tagObject">http://swagger.io/specification/#tagObject</a></span></div><div><span style="color:rgb(0,0,0);font-family:arial,helvetica,sans-serif">6. </span><span style="color:rgb(0,0,0);font-family:arial,helvetica,sans-serif"><a href="http://developer.openstack.org/api-ref-compute-v2.html#compute_servers">http://developer.openstack.org/api-ref-compute-v2.html#compute_servers</a></span></div><div><span style="color:rgb(0,0,0);font-family:arial,helvetica,sans-serif">7. </span><span style="color:rgb(0,0,0);font-family:arial,helvetica,sans-serif"><a href="http://fairy-slipper.russellsim.org/rst/compute-v2-swagger-tags.rst">http://fairy-slipper.russellsim.org/rst/compute-v2-swagger-tags.rst</a></span></div><div>8. <a href="http://developer.openstack.org/api-ref-compute-v2.html#compute_server_metadata">http://developer.openstack.org/api-ref-compute-v2.html#compute_server_metadata</a></div><div><br>-- </div><div class="gmail_signature"><div dir="ltr">Cheers,<br>Russell Sim</div></div>
</div></div>