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

Answer 3

The reason why it's deprecated is that previous Swagger versions (1.x) used the @Api description annotation to group operations.

In the Swagger 2.0 specification, the notion of tags was created and made a more flexible grouping mechanism. To be API compliant, the description field was retained so upgrades would be easy, but the correct way to add a description is though the tags attribute, which should reference a @Tag annotation. The @Tag allows you to provide a description and also external links, etc.

Answer 4

I tried above solutions but they didn't work for me.

To add a title and description to the documentation you create ApiInfo and Contact objects like in example below. Then you simply add apiInfo object to your Swagger Docket.

import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;

@EnableSwagger2
@Configuration
public class SwaggerConfig {

  private Contact contact = new Contact("", "", "");
  private ApiInfo apiInfo = new ApiInfo(
      "Backoffice API documentation",
      "This page documents Backoffice RESTful Web Service Endpoints",
      "1.0",
      "",
      contact,
      "",
      "");

  @Bean
  public Docket api() {
    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(apiInfo)
        .select()
        .apis(RequestHandlerSelectors.basePackage(
            PaymentsController.class.getPackage().getName()
        ))
        .paths(PathSelectors.ant("/api/v1/payments" + "/**"))
        .build()
        .useDefaultResponseMessages(false)
        .globalOperationParameters(
            newArrayList(new ParameterBuilder()
                .name("x-authorization")
                .description("X-Authorization")
                .modelRef(new ModelRef("string"))
                .parameterType("header")
                .required(false)
                .build()));
  }
}

Above code produces a description like in a screenshot below.

Answer 5

I too wondered what to do about uses of the deprecated description (showing up as warnings in my IDE).

Well, on closer inspection it turned out that description is not used anywhere in Swagger UI. After that the solution (in our case*) became clear: simply remove those descriptions.

(*In our codebase, with clean class and method names etc, there was certainly no need for such "API descriptions" for the reader of the code. I would have tolerated having these bits of Swagger-related noise in the codebase if they added some value in Swagger UI, but since they didn't, the only sensible thing was to throw them away.)

Answer 6

I found that the following works by combining both the @Api and @Tag annotations building off of this answer.

The value within the tags field of the @Api annotation needs to match the value within the name field of the @Tag annotation.

@Api(tags = "Controller API")
@Tag(name = "Controller API", description = "This controller performs API operations")
public class ReportStatusConsumerController {

}

Answer 7

An old question but may help using swagger 3

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    // Swagger configuration
    @Bean
    public Docket api() {

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo( this.apiInfo())
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("API Reference").version("1.0.0")
                .description("something")
                .license("Apache 2.0")
                .build();
    }

    public void addResouceHandler(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}