Swagger 1.5 Doesn't Display My 1.2's @Api Description?

I managed to eventually solve the issue by understanding a couple of concepts:

1. API endpoints (that usually have the @Api annotation) are grouped by Tag, not by resource. This can make, for example, an operation be listed under more than one category. Tags can, but not have to, be derived from the value attribute of the @Api annotation – the one that usually starts with a slash. This makes the grouping, and hence the UI, behave almost the same when migrating, but also caused me the confusion of not realizing the description attribute is ignored – something must be reading that, right?

2. Tags are first-class citizens in Swagger's specs (see here). They are extensible and can have descriptions, as mentioned in this comment.

3. One can add tags or enhance existing ones by programmatically apply the @Tag annotation to any resource discoverable by Swagger. Just pick a resource and list the desired descriptions there – but be sure to have them in only one place. Lucky for me, I happen to have an abstract class all the resources extend. So it was possible for me to write the descriptions in the most natural place, given the circumstances:

   import io.swagger.annotations.Contact; import io.swagger.annotations.Info; import io.swagger.annotations.SwaggerDefinition; import io.swagger.annotations.Tag; 

   and then

   @SwaggerDefinition( info = @Info( title = "My API", version = "0.1", contact = @Contact(name = "Me", email = "[email protected]") ), tags = { @Tag( name = "pets", description = "Manage pets" ), @Tag( name = "search", description= "Search pets" ), ... } ) public class BaseResource { ... } 

Voila! The old-new descriptions can be exhibited after compiling and firing up the UI, just like one can see at the aforementioned comment. Achievement unlocked.

To really seal the deal, one can now delete @Api's description attribute from your resources, as the description is inferred from the @Tag specifications.