java - Api 注释的描述已弃用

Question

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

Deprecated. Not used in 1.5.X, kept for legacy support.

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

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