Api annotation's description is deprecated

Question

In Swagger, the @Api annotation's description element is deprecated.

Deprecated. Not used in 1.5.X, kept for legacy support.

Is there a newer way of providing the description?

Answer 1

I found two solutions for Spring Boot application:

1. Swagger 2 based:

Firstly, use the tags method for specify the tags definitions in your Docket bean:

@Configuration @EnableSwagger2 public class Swagger2Config {          public static final String TAG_1 = "tag1";      @Bean     public Docket productApi() {         return new Docket(DocumentationType.SWAGGER_2).select()                 .apis(RequestHandlerSelectors.basePackage("my.package")).build()                 .tags(new Tag(TAG_1, "Tag 1 description."))                 // Other tags here...                 .apiInfo(apiInfo());     }      private ApiInfo apiInfo() {         return new ApiInfoBuilder().title("My API").version("1.0.0").build();     } } 

After, in RestController just add the @Api annotation with one (or more) of the your tags:

@Api(tags = { SwaggerConfig.TAG_1 }) @RestController @RequestMapping("tag1-domain") public class Tag1RestController { ... } 

2. Swagger 3 based (OpenAPI):

Similarly, use the addTagsItem method for specify the tags definitions in your OpenAPI bean:

@Configuration public class OpenApiConfig {      public static final String TAG_1 = "tag1";      @Bean     public OpenAPI customOpenAPI() {         final Info info = new Info()                 .title("My API")                 .description("My API description.")                 .version("1.0.0");          return new OpenAPI().components(new Components())                 .addTagsItem(createTag(TAG_1, "Tag 1 description."))                 // Other tags here...                 .info(info);     }      private Tag createTag(String name, String description) {         final Tag tag = new Tag();         tag.setName(name);         tag.setDescription(description);         return tag;     }  } 

Finally, in RestController just add the @Tag annotation:

@Tag(name = OpenApiConfig.TAG_1) @RestController @RequestMapping("tag1-domain") public class Tag1RestController { ... } 

Answer 2

This is the correct way to add description to your Swagger API documentation for Swagger v1.5:

@Api(tags = {"Swagger Resource"}) @SwaggerDefinition(tags = {     @Tag(name = "Swagger Resource", description = "Write description here") }) public class ... { }