<!-- 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 // 標(biāo)識為配置類
@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()
                // 配置接口掃描規(guī)則：只掃描帶有 @ApiOperation 注解的方法
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any()) // 匹配所有路徑
                .build()
                .enable(true); // 是否啟用 Swagger（生產(chǎn)環(huán)境可設(shè)為 false 關(guān)閉）
    }
 
    /**
     * 配置 API 文檔頁面信息（標(biāo)題、描述、版本等）
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot API 文檔") // 文檔標(biāo)題
                .description("接口文檔詳情：包含用戶管理、數(shù)據(jù)查詢等接口") // 文檔描述
                .version("1.0.0") // 接口版本
                .contact(new Contact("開發(fā)者", "https://xxx.com", "xxx@example.com")) // 聯(lián)系人信息
                .license("Apache 2.0") // 許可協(xié)議
                .licenseUrl("https://www.apache.org/licenses/LICENSE-2.0") // 許可協(xié)議鏈接
                .build();
    }
 
    /**
     * 配置靜態(tài)資源映射（解決 Swagger UI 頁面無法訪問問題）
     */
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        // 映射 Swagger UI 靜態(tài)資源
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        // 映射 webjars 靜態(tài)資源（Swagger UI 依賴的前端資源）
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
        // 映射項(xiàng)目自定義靜態(tài)資源（如需要）
        registry.addResourceHandler("/**")
                .addResourceLocations("classpath:/static/");
    }
}

spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher # 切換為 Ant 風(fēng)格路徑匹配器

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 = "獲取數(shù)據(jù)庫中所有人員信息列表") // 描述方法作用
    @RequestMapping("/findAll")
    @ResponseBody
    public List<Person> findAll() {
        return personService.findAll();
    }
 
    @ApiOperation(value = "添加人員", notes = "根據(jù)傳入的人員信息新增一條記錄")
    @RequestMapping("/insert")
    @ResponseBody
    public String insert(
            @ApiParam(name = "person", value = "人員實(shí)體對象", required = true) // 描述參數(shù)
            Person person) {
        int result = personService.insert(person);
        return result > 0 ? "插入成功" : "插入失敗";
    }
 
    @ApiOperation(value = "刪除人員", notes = "根據(jù) 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>