我来帮你梳理下解决思路，结合你遇到的@Api描述弃用、@SwaggerDefinition不生效的情况，给你几个可行的方案：

1. 给单个API路径（接口方法）添加描述 #

如果你想给每个具体的接口路径加描述，直接在方法上用@ApiOperation注解就可以了，它的value字段是接口的简短标题，notes字段用来写详细描述，这两个内容都会在Swagger UI里清晰显示：

@RestController
public class UserController {

    @GetMapping("/users/{id}")
    @ApiOperation(value = "根据ID查询用户", notes = "传入用户唯一ID，返回包含用户名、邮箱、注册时间的完整用户信息，ID需大于0")
    public User getUserById(@PathVariable Long id) {
        // 业务逻辑实现
    }
}

2. 给Controller级别的路径组添加描述 #

原来@Api的description属性被弃用后，推荐用@Tag注解（Swagger 2.9.0及以上版本支持）来给整个Controller的接口组加描述：

@RestController
@Tag(name = "用户管理接口组", description = "负责用户的创建、查询、更新、删除，以及权限配置等核心操作")
public class UserController {
    // 接口方法
}

如果你的Swagger版本较低，也可以通过@SwaggerDefinition全局配置标签描述，但要注意和Controller上@Api(tags)的名称完全对应：

@SwaggerDefinition(
    info = @Info(title = "我的Web服务API文档", version = "1.0"),
    tags = {
        @Tag(name = "用户管理接口组", description = "负责用户的创建、查询、更新、删除，以及权限配置等核心操作"),
        @Tag(name = "订单管理接口组", description = "处理订单的下单、支付、物流查询、退款等流程")
    }
)
@Configuration
@EnableSwagger2
public class SwaggerConfig {
    // 其他配置
}

3. 确保Swagger配置正确加载 #

还要检查你的Swagger配置类是否正确生效：

• 必须加上@EnableSwagger2注解开启Swagger功能
• 配置Docket实例时要指定扫描的包路径，确保Controller被扫描到
• 可以通过apiInfo()设置全局的API文档描述，这个会显示在Swagger UI的顶部：

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.your.project.controller"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Web服务API文档")
                .description("这是全局的API文档说明，涵盖用户管理、订单管理等多个模块")
                .version("1.0")
                .build();
    }
}

4. 常见问题排查 #

• 检查Springfox版本：建议使用2.9.0及以上版本，旧版本对新注解的支持不完善
• 确认Spring Boot和Swagger的版本兼容性：比如Spring Boot 2.1.x搭配Springfox 2.9.0，更高版本的Spring Boot建议切换到SpringDoc（OpenAPI 3）
• 确保没有通过配置关闭Swagger的显示（比如生产环境禁用的配置）

内容的提问来源于stack exchange，提问作者user666