Open Stack

On 29 June 2015 at 23:03, Karen Bradshaw <kbhawkey at gmail.com> wrote:

> Hi, Russell.  I just started to look at this code but thought of a few
> questions,
> 1) How did you validate the generated swagger-json files?
>

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.

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.

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.


> 2) Did you create a new schema, Swagger 2.0-OpenStack?  What
> does it look like?
>

Yes.

So there are 3 modifications that we are currently using.

1.  Swagger doesn't support request examples.

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].

2. Swagger doesn't support multiple duplicate operations
(get/put/post/delete/head) at the same url

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]

Basically this is a big no-no in REST, so swagger outright doesn't support
it.

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)

e.g. normal swagger

{
"paths": {
"/v2/​{tenant_id}​/servers/​{server_id}​/action": {
"get": {
"responses": {
"200": {

our swagger

{
"paths": {
"/v2/​{tenant_id}​/servers/​{server_id}​/action": [
{"method": "get",
"responses": {
"200": {

3.  Swagger doesn't support extended documentation of Tags.

Put simply Tags are used group the API calls.  So all the folding bits in
the demo at [4].

They only support the single line of text. So for the Tag image-metadata,
the Tag's description is  "Image metadata" [5].

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)

This extended documentation makes it's way into the ReST files [7] but
currently the Swagger-UI we are using doesn't display it.

NB, I did spot the conversion issues :(


> 3) Can you elaborate a bit more about the tagging system?
>

So, the tagging system works like this.

Each REST endpoint/method (swagger calls them operations)  e.g. POST
​{tenant_id}​/servers.  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.

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.

0. http://swagger.io/specification/#operationObject
1. http://swagger.io/specification/#exampleObject
2.
http://developer.openstack.org/api-ref-compute-v2.html#compute_server-actions
4. http://fairy-slipper.russellsim.org/swagger-ui/
5. http://swagger.io/specification/#tagObject
6. http://developer.openstack.org/api-ref-compute-v2.html#compute_servers
7. http://fairy-slipper.russellsim.org/rst/compute-v2-swagger-tags.rst
8.
http://developer.openstack.org/api-ref-compute-v2.html#compute_server_metadata

-- 
Cheers,
Russell Sim
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20150630/713b2836/attachment.html>