Replacement For description field of @Api Annotation In Jersey API?

[Saad Mufti]

Hi,

We're upgrading from Swagger 1.3.x to Swagger 1.5.x . Everything is working pretty smoothly, except that we cannot figure out a replacement for the description field of the @Api annotation.

The docs state that the value of the @Api annotation is treated like a tag now that gets auto-created if not already defined in your swagger config, but the description field is deprecated and not used, I am guessing because the tag used in @Api can be repeated on other classes. The Swagger UI thus comes up with no description for each section/tag, only one for the overall API that was set at initialization.

Our attempt to fix this after reading some docs was to set the description directly in the Swagger config at initialization as follows in our Jersey custom Application class:

     packages("io.swagger.jaxrs.listing");

      // configure swagger

      final BeanConfig config = new BeanConfig();

      config.setVersion("1.0");

      config.setBasePath(properties.getProperty("swagger.api.basepath"));

         .

         .

         .

      config.setPrettyPrint(true);

      config.getSwagger()

          .tag(new Tag().name("advertiser_create").description("Create advertiser"))

          .tag(new Tag().name("advertiser_find").description("Find advertisers with given properties"))

          .tag(new Tag().name("advertiser").description("Operations on advertiser"));

      config.setScan(true);

The same tag values used in initialization above are repeated in @Api annotations on our actual Jersey resource classes.

But at runtime, it appears that when we call the swagger.json endpoint, it is constructing a Swagger object of its own by scanning everything again, as far as I can tell. At least the Swagger object it constructs is different from the one used in initialization above, thus the various tags again have no description even though one was set in the initialization code above.The same is reflected in the Swagger UI which shows the various tag/sections with no title.

I would appreciate some guidance on how to achieve this, clearly I must be misunderstanding something.

Thanks.

----

Saad

[Ron Ratovsky]

Hi Saad,

Kudos for figuring out why we deprecated the @Api description - not many realize that was the issue.

There are two ways to configure the tag descriptions:

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

2. Second is following https://github.com/swagger-api/swagger-core/wiki/Annotations-1.5.X#swaggerdefinition (check out the example code)

Let me know if you encounter any issues when trying either approach.

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

[Saad Mufti]

Thanks. The @SwaggerDefinition annotation did the trick, as we're using BeanConfig in a custom Application sub-class to initialize Swagger. We added the tag descriptions in a SwaggerDefinition annotation on the same Application class and Swagger then merged those tags with the other Swagger config we set up via the BeanConfig class.

----

Saad

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggersocket+unsub...@googlegroups.com.

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