no path description allowed in 2.0?

[David Biesack]

Swagger 1.2 had a top level file that listed the API roots

and descriptions for them

```

 "apis" : [ { "description" : "Operations about pets",

        "path" : "/pet"

      },

      { "description" : "Operations about user",

        "path" : "/user"

      },

      { "description" : "Operations about store",

        "path" : "/store"

      }

    ],

```

whchh you can see at http://petstore.swagger.wordnik.com/

Swagger 2.0 does not have this. I can provide a description for the API in the info section

but I cannot group resources as above. Also, Swagger 2.0 does not allow

a description in a path so the top level swagger UI is pretty void of commentary.

so the spec

```

{

    "swagger": "2.0",

    "info": {

        "title": "Where are the descriptions?",

        "version": "1"

    },

    "host": "www.example.com",

    "basePath": "/sample",

    "schemes": [ "http" ],

    "paths": {

        "/foos": {

            "get": {

                "description": "get foos",

                "produces": [

                    "application/json",

                    "application/xml"

                ],

                "responses": {

                    "200": {

                        "description": "links to the resource collections in this API"

                    }

                }

            }

        },

        "/foos/{id}": {

            "get": {

                "description": "get a foo",

                "produces": [

                    "application/json",

                    "application/xml"

                ],

                "responses": {

                    "200": {

                        "description": "links to the resource collections in this API"

                    }

                }

            }

        }

    }

}

```

yields the barren

(I can expand operations to see the description but I'd rather see it, or a title, here).

Is this a known/reported bug in the spec? (I could not find it)

[Ron]

Actually, 1.2 didn't allow descriptions for paths but rather for resources (which are a collection of paths).

In 2.0 we changed the way operations are groups, introducing the "tags" property for an operation which is an array of strings.

Each operation can have one or more tags. Operations with no tags will fall under the 'default' category by the UI.

There's also a top-level tags property which allow you to add description to them, just like you could in 1.2.

--
You received this message because you are subscribed to the Google Groups "Swagger" group.
To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggers...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[David Biesack]

Can someone provide an example of using these tags - i.e. how can I group paths into resources,

and how can I supply description strings for the resources in Swagger UI, and how can I provide descriptions

for the paths - i.e. Swagger is supposed to help document my REST API, but it's not obvious how to do that!

[David Biesack]

I've figured out how to do this; the purpose was not obvious from the spec (and lack of examples did not help) but

the hint from Ron R helps - I can add an array of tags in my info block, and then list those tags in my operations

in order to group my operations by resource.

I can also add a "summary" to each operation to get the operation short description in Swagger-UI. 

[Rohit Reddy Aguvaveedhi Reddy]

I am trying to provide/change descriptions for the tags. Currently, the tags use the "description" property of the first operation(they are listed in) as their description. Sample of the spec:

{

    "swagger": "2.0",

    "info": {

        "version": "1.0",

        "title": "Swagger - 2.0 specification",

        "description": "API using swagger-2.0 specification",

        "termsOfService": "http://termsofservice.com",

        "contact": {

            "name": "Support",

            "url": "http://www.example.com/contact-us/",

            "email": "sup...@example.com"

        },

        "license": {

            "name": "License",

            "url": "http::/linktolicense"

        }

    },

    "host": "example",

    "basePath": "/sample",

    "schemes": [

        "http"

    ],

    "consumes": [

        "application/json"

    ],

    "produces": [

        "application/json"

    ],

    "paths": {

        "/foo/{param}": {

            "get": {

                "tags": [

     "mytag"

],

                "summary": "List accounts",

                "description": "Required parameter is an XXXXX"

                "operationId": "account_list",

                "parameters": [

                    {

                        "in": "path",

                        "name": "XXXXXXXX",

                        "description": "Sample description",

                        "required": true,

                        "type": "integer",

                        "format": "int32"

                    }

                ],

                "responses": {

                    "200": {

                        "description": "success response",

                        "schema": {

                            "$ref": "#/definitions/result_model"

                        }

                    }

                }

            }

        }

   }

}

I tried adding the below json block to be used as the "top-level" tags property outside the "paths" block.

 "tags": [ 

      {

            "name": "mytag", 

             "description": "Operation for mytag" 

      } 

 ],

Is there a known/different way to do this?

[tony tam]

Hi Rohit, I believe you need swagger-ui-2.1.5-M1 or later to do this.  If you grab the latest from github/npmjs.org and look at the petstore sample at http://petstore.swagger.io/v2/swagger.json you'll see it working as you described it.

[Rohit Reddy Aguvaveedhi Reddy]

Thanks Tony, the new update seemed to do it.