Support for 2.0 tags and extension properties in swagger-core and swagger-ui

[James S.]

Hi, we really like Swagger 2.0's support for tags (https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#tag-object-) and extensions properties (https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#specification-extensions-) as these features will allow us to attach metadata to our APIs, enabling us to develop tools that will read/process this extra meta-data.

I am trying to find out what is the support for tags and extension properties in swagger-core. From what I could gather, the value passed to the @Api annotation is automatically used as the tag for all operations under that API, and there is currently no way to specify more tags. The @ApiOperation annotation does have a "tags" property but that one is just a placeholder for now.

I have also found https://github.com/swagger-api/swagger-core/issues/841 (milestone v1.5-M2) which I believe will handle tag definitions at the Swagger object level. What about extension properties, are there plans for supporting them via annotations in swagger-core?

On the swagger-ui it seems like tags are used to group the operations together under the collapsible heading, which kinda makes sense, given the main purpose of tags. Any plans on making extension properties visible somehow? Although these extensions are mostly for consumption by tools, in our case we'd actually want the human user that views the UI to be aware them. 

Thanks,

James

[tony tam]

Hi, great timing!  I'm literally just wrapping up first support for tags right now.  The UI (as of 2.1.5-M1) now supports tags + descriptions, and swagger-core will shortly as well.  I suspect there will be a 1.5.2-M1 release very shortly, and you will be able to get a 1.5.2-M1-SNAPSHOT within an hour.

[tony tam]

OK you can pull 1.5.2-M1-SNAPSHOT from sonatype snapshots.  An updated sample lives in the samples/java-jaxrs folder:

https://github.com/swagger-api/swagger-core/blob/develop_2.0/samples/java-jaxrs/src/main/java/com/wordnik/swagger/sample/resource/PetResource.java#L31-L41

Note that you need swagger-ui 2.1.5 or greater to see the tag descriptions.  ALSO the externalDocs are NOT rendered in the UI yet, but you will see them in the swagger.json

[James S.]

Thanks Tony, I was able to see the improvements in this latest version.

It seems like there is a slight mismatch between how tags are implemented in swagger-core and how they are specified in the specification.

In the specification, tags (and their description, URL, etc) are defined at the root Swagger object level and then referenced (or not) by Operations across the different Paths. Additionally, the specification makes it clear that it is possible to use a tag in an Operation even if it is not defined at the root Swagger object level.

In swagger-core, tags are defined and referenced in the @Api annotation, which corresponds roughly to the Path object in the specification.

This carries the following implications:

• All Operations under that Path are tagged with that tag. So it is not possible to have only half of the Operations in a resource class tagged with a certain tag.
  
• It is not possible to tag Operations implemented in different resources with the same tag, because that would imply defining the same tag twice. I actually tried defining the same tag in different resources to see what would happen and one of the resources is simply not included in the resulting swagger file (presumably because of some error that occurs while building the Swagger model).
  
• Finally, it is not possible to tag a method with a tag that is not defined in the root Swagger definition.
  

To give a bit more context about the sort of thing we are evaluating Swagger for: we would like to build an Excel plugin that can read the API documentation for a service (in Swagger format), find all operations tagged with a special tag, for example "available-in-excel", and make those operations available as Excel function that calls the appropriate service when called, etc. This would require a finer control of which Operations are tagged. Something like this could also be achieved with the extension properties as well, but I don't think there's support from swagger-core for that yet.

Thanks,

James

[tony tam]

Hi James, you are correct, and the current implementation is not complete/correct.  I will make sure it follows the spirit of the spec before the next swagger-core release goes out.  I was using this as the first implementation for the annotations, and the top-level (@Api annotation) to verify that the code style would be OK.

[James S.]

Thanks, this is much appreciated!

--
You received this message because you are subscribed to a topic in the Google Groups "Swagger" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/swagger-swaggersocket/ZTGClcvoqY8/unsubscribe.
To unsubscribe from this group and all its topics, send an email to swagger-swaggers...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[tony tam]

Hi, this is now fully supported in 1.5.2-M1.  Give it a whirl...

To unsubscribe from this group and all its topics, send an email to swagger-swaggersocket+unsub...@googlegroups.com.

[tony tam]

Also you can see an example here:

http://generator.swagger.io

With source here:

https://github.com/swagger-api/swagger-codegen/blob/e5c70d596165e105b9e402e3a3bd79d8790290ed/modules/swagger-generator/src/main/java/com/wordnik/swagger/generator/resource/SwaggerResource.java

[James S.]

Hi Tony, I've had a chance to test this a bit and it seems to be working.

The Swagger UI might have to be tweaked eventually to allow it to better work with multiple tags, but this is a question for that project :)

Thank you,

James

To unsubscribe from this group and all its topics, send an email to swagger-swaggers...@googlegroups.com.

[Dustin Johnson]

I'm confused by this example. I'm trying to figure out how to get the @Api description into the correct place in the generated spec. In your example it looks like the description for "/gen' (the description is "Resource for generating swagger components") gets lost. Shouldn't the description appear as a description property along side the name property within the tag definition?

I expect something like this:

"tags": [

    {

        "name": "gen",

        "description": "Resource for generating swagger components"

    },

    ...

]

[Ron Ratovsky]

Hi Dustin,

Due to the way tags are generated/controlled, the behavior in 1.5 has changed.

We've made note in the annotation javadocs that the @Api#description() is now deprecated - http://docs.swagger.io/swagger-core/current/apidocs/io/swagger/annotations/Api.html#description().

To set the description for tags, you now have two ways.

Method 1 - https://github.com/swagger-api/swagger-samples/blob/master/java/java-jersey-jaxrs/src/main/java/io/swagger/sample/Bootstrap.java#L36-L46.

Method 2 - http://swagger.io/customizing-your-auto-generated-swagger-definitions-in-1-5-x/

To unsubscribe from this group and all its topics, send an email to swagger-swaggers...@googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

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

--

-----------------------------------------

http://swagger.io
https://twitter.com/SwaggerApi
-----------------------------------------