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