CODEWITHSUNDEEP
javadropwizardswagger-uiswagger-2.0
MrMister
MrMister

Reputation: 2536

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

I recently upgraded a project from Swagger API 1.2 to 2.0 (or, speaking in Swagger-core terms, from 1.3 to 1.5). Because of their excellent migration guide, I managed to do that in a very short time and almost without a hitch. The only thing that is bugging me is the lack of support for the @Api annotation's description value. The endpoints were meticulously documented - up to and including the top-level API endpoints - but their descriptions ceased to be showed in the UI:

example Notice that something's missing?

Some research (meaning, reading the source code) yielded that the same descriptions are now obsolete, making room for fancier @Tag annotations. But I couldn't find information on how to apply them so the descriptions would still be in each endpoint class.

Using just Dropwizard, is there a way to programmatically make this happen in Swagger 1.5?

Upvotes: 4

Views: 2681

Answers (1)

MrMister
MrMister

Reputation: 2536

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.

Upvotes: 6

Related Questions