Swagger 是一个用于 生成、描述、调用和可视化 RESTful Web 服务 的强大工具。它现在被称为 OpenAPI 规范。我们常用的是配合 Spring Boot 项目来自动生成 API 文档。

✅ 一、引入依赖

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.7.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.7.0</version>
</dependency>
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>2.0.9</version>
</dependency>

✅ 二、添加配置类

​
​
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
​
@Configuration
@EnableSwagger2
public class SwaggerConfig {
​
    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.asdre.biz.lt.web.controller"))
                .paths(PathSelectors.any())
                .build();
    }
    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("API文档")
                .description("API文档")
                .version("2.0")
                .build();
    }
​
}

  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

✅ 三、在接口和参数上使用注解

java复制编辑@RestController
@RequestMapping("/user")
@Api(tags = "用户管理接口") // 控制器上的描述
public class UserController {
​
    @GetMapping("/{id}")
    @ApiOperation("根据ID查询用户") // 接口描述
    public UserVO getUserById(@PathVariable @ApiParam("用户ID") Long id) {
        // ...
    }
​
    @PostMapping("/add")
    @ApiOperation("新增用户")
    public void addUser(@RequestBody @Validated @ApiParam("用户信息") UserReq req) {
        // ...
    }
}

✅ 四、常用注解

✅ 五、访问文档页面

如果一切配置正常，项目启动后默认访问地址是：

http://localhost:9090/doc.html

http://localhost:8080/swagger-ui/

或者：

http://localhost:8080/swagger-ui/index.html

✅ 你也可以使用 Swagger 生成接口文档 JSON：

http://localhost:8080/v3/api-docs

如果你用的是 Spring Boot 3.x，我建议使用 springdoc-openapi，要不要我给你单独贴一版 Spring Boot 3.x 的 Swagger 用法？