SpringBoot集成Swagger2构建可视化API文档的完整步骤

<!-- Swagger2 核心依赖 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<!-- Swagger2 可视化界面 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

package com.qcby.springboot.config;
 
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
 
@Configuration // 标识为配置类
@EnableSwagger2 // 启用 Swagger2
public class SwaggerConfig implements WebMvcConfigurer {
 
    /**
     * 配置 Swagger 核心对象 Docket
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2) // 指定 Swagger 版本为 2.x
                .apiInfo(apiInfo()) // 配置 API 文档基本信息
                .select()
                // 配置接口扫描规则：只扫描带有 @ApiOperation 注解的方法
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any()) // 匹配所有路径
                .build()
                .enable(true); // 是否启用 Swagger（生产环境可设为 false 关闭）
    }
 
    /**
     * 配置 API 文档页面信息（标题、描述、版本等）
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot API 文档") // 文档标题
                .description("接口文档详情：包含用户管理、数据查询等接口") // 文档描述
                .version("1.0.0") // 接口版本
                .contact(new Contact("开发者", "https://xxx.com", "xxx@example.com")) // 联系人信息
                .license("Apache 2.0") // 许可协议
                .licenseUrl("https://www.apache.org/licenses/LICENSE-2.0") // 许可协议链接
                .build();
    }
 
    /**
     * 配置静态资源映射（解决 Swagger UI 页面无法访问问题）
     */
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        // 映射 Swagger UI 静态资源
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        // 映射 webjars 静态资源（Swagger UI 依赖的前端资源）
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
        // 映射项目自定义静态资源（如需要）
        registry.addResourceHandler("/**")
                .addResourceLocations("classpath:/static/");
    }
}

spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher # 切换为 Ant 风格路径匹配器

package com.qcby.springboot.controller;
 
import com.qcby.springboot.entity.Person;
import com.qcby.springboot.service.PersonService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.ResponseBody;
 
import java.util.List;
 
@Api(tags = "人员管理接口") // 描述类的作用
@Controller
@RequestMapping("/person")
public class PersonController {
 
    @Autowired
    private PersonService personService;
 
    @ApiOperation(value = "查询所有人员", notes = "获取数据库中所有人员信息列表") // 描述方法作用
    @RequestMapping("/findAll")
    @ResponseBody
    public List<Person> findAll() {
        return personService.findAll();
    }
 
    @ApiOperation(value = "添加人员", notes = "根据传入的人员信息新增一条记录")
    @RequestMapping("/insert")
    @ResponseBody
    public String insert(
            @ApiParam(name = "person", value = "人员实体对象", required = true) // 描述参数
            Person person) {
        int result = personService.insert(person);
        return result > 0 ? "插入成功" : "插入失败";
    }
 
    @ApiOperation(value = "删除人员", notes = "根据 ID 删除指定人员记录")
    @RequestMapping("/delete")
    @ResponseBody
    public String delete(
            @ApiParam(name = "id", value = "人员 ID", required = true, example = "1")
            Integer id) {
        int result = personService.delete(id);
        return result > 0 ? "删除成功" : "删除失败";
    }
}

<!-- 替代 Swagger2 的 OpenAPI 3.0 依赖 -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.2.0</version>
</dependency>