Api 注释的描述已弃用

Question

在 Swagger 中， @Api 注释的 description 元素已弃用。

已弃用。 未在 1.5.X 中使用，保留用于遗留支持。

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

原文由 Soumitri Pattnaik 发布，翻译遵循 CC BY-SA 4.0 许可协议

Answer 1

我为 Spring Boot 应用程序找到了两个解决方案：

1. 基于 Swagger 2 ：

首先，使用 tags 方法在你的 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();
    }
}

之后，在 RestController 只需添加 @Api 带有一个（或多个）你的标签的注释：

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

2. 基于 Swagger 3 (OpenAPI)：

同样，使用 addTagsItem 方法在你的 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;
    }

}

最后，在 RestController 中添加 @Tag 注释：

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

原文由 falvojr 发布，翻译遵循 CC BY-SA 4.0 许可协议