Api annotation's description is deprecated

问题:

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

Is there a newer way of providing the description?

回答1:

I found a solution for my Spring Boot application. Firstly, use the tags method for specify the tags definitions in your Docket:

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket productApi() {
        return new Docket(DocumentationType.SWAGGER_2).select()
                .apis(RequestHandlerSelectors.basePackage("my.package")).build()
                .apiInfo(apiInfo())
                .tags(new Tag("tag1", "Tag 1 description."),
                        new Tag("tag2", "Tag 2 description."),
                        new Tag("tag2", "Tag 3 description."));
    }

    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. For example:

@Api(tags = { "tag1" })
@RestController
@RequestMapping("tag1Domain")
public class Tag1RestController { ... }

回答2:

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

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

回答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.

回答4:

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