不推荐使用Api注释的描述

Question

在Swagger中,不推荐使用@Api注释description.

有没有更新的方式来提供描述？

Answer 1

我找到了Spring Boot应用程序的解决方案.首先,使用该tags方法在以下内容中指定标记定义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();
    }
}

之后,RestController只需添加@Api一个(或多个)标签的注释即可.例如:

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

Answer 2

弃用它的原因是以前的 Swagger 版本 (1.x) 使用@Api描述注释来对操作进行分组。

在 Swagger 2.0 规范中，tags创建了 的概念并使分组机制更加灵活。为了与 API 兼容，该description字段被保留以便升级很容易，但添加描述的正确方法是通过tags属性，它应该引用一个@Tag注释。将@Tag允许您提供的描述，外部链接等。

Answer 3

这是向v1.5的Swagger API文档添加描述的正确方法：

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