一文吃透 Springfox-Swagger2：接口文档配置 + 注解全解析

在前后端分离或微服务架构的开发模式下，API 文档的可读性和完整性直接影响开发效率。Swagger2 作为一款优秀的 API 文档生成工具，能自动同步 API 文档与代码、支持在线调试，极大降低文档维护成本。本文详细讲解在 Spring Boot 中集成 Swagger2 的完整流程、配置细节及核心注解的使用方式。

一、Swagger2 依赖引入

首先需在 Spring Boot 项目的 pom.xml 中引入 Swagger2 核心依赖，本文选用稳定的 2.9.2 版本（适配大部分 Spring Boot 2.x 版本）。

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

注意事项：

1. 若项目中存在 Spring Security 或 Shiro 等权限框架，需放行 Swagger 相关路径（如 /swagger-ui.html、/v2/api-docs、/swagger-resources/**），否则无法访问文档界面；
2. 高版本 Spring Boot（如 2.6.x+）需额外配置 spring.mvc.pathmatch.matching-strategy=ant_path_matcher，解决路径匹配冲突问题。

二、Swagger2 核心配置

通过自定义配置类开启 Swagger2，并对文档分组、接口过滤、响应信息、联系人等核心信息进行配置。

2.1 核心配置类

import com.google.common.collect.Lists;
import com.google.common.collect.Sets;
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.service.Contact;
import springfox.documentation.service.ResponseMessage;
import springfox.documentation.service.Tag;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import javax.servlet.http.HttpServletRequest;
/**
 * Swagger2 配置类
 * 核心说明：
 * 1. @EnableSwagger2：开启 Swagger2 自动文档生成功能；
 * 2. Docket：每个 Docket 对应一个 API 分组，可通过 apis/paths 实现接口过滤；
 * 3. 支持全局配置响应信息、协议、请求/响应类型等通用属性。
 */
@Configuration
@EnableSwagger2 // 开启 Swagger2 自动生成文档功能
public class SwaggerConfig {
  /**
   * 定义订单导出 API 分组
   * @return Docket 文档构建器
   */
  @Bean
  public Docket api() {
    // 1. 定义接口标签（可配置分组描述）
    Tag orderExportTag = new Tag("订单导出api", "订单相关导出接口，包含订单数据查询、导出任务提交等功能");
    // 2. 定义全局通用响应信息（500 系统异常）
    ResponseMessage systemErrorResponse = new ResponseMessageBuilder()
        .code(500)
        .message("系统异常，请联系管理员处理")
        .build();
    return new Docket(DocumentationType.SWAGGER_2)
        // 是否使用默认响应信息（关闭后使用自定义全局响应）
        .useDefaultResponseMessages(false)
        // 全局配置 GET 请求的响应信息
        .globalResponseMessage(HttpServletRequest.GET, Lists.newArrayList(systemErrorResponse))
        // 配置文档基础信息
        .apiInfo(apiInfo())
        // 分组名称（可在 UI 界面切换不同分组）
        .groupName("订单导出api")
        // 支持的传输协议
        .protocols(Sets.newHashSet("http", "https"))
        // 接口接收的请求数据类型
        .consumes(Sets.newHashSet("application/json"))
        // 接口返回的响应数据类型
        .produces(Sets.newHashSet("application/json"))
        // 绑定标签
        .tags(orderExportTag)
        // 接口筛选规则
        .select()
        // 指定生成文档的接口包路径
        .apis(RequestHandlerSelectors.basePackage("com.zhen.export"))
        // 匹配所有路径（可通过 PathSelectors.ant("/xxx/**") 指定特定路径）
        .paths(PathSelectors.any())
        .build();
  }
  /**
   * 配置 API 文档基础信息（标题、描述、联系人等）
   * @return ApiInfo 文档元信息
   */
  private ApiInfo apiInfo() {
    return new ApiInfoBuilder()
        // 文档标题
        .title("珍品导出系统 API 文档")
        // 文档详细描述
        .description("珍品导出系统 API 文档，包含订单导出、数据查询、任务管理等核心接口，支持 HTTP/HTTPS 协议，所有接口均返回 JSON 格式数据")
        // 联系人信息（姓名、网址、邮箱）
        .contact(new Contact("moon", "https://www.baidu.com", "moon@zhen.com"))
        // 文档版权声明
        .license("MIT License")
        // 版权声明链接
        .licenseUrl("https://opensource.org/licenses/MIT")
        // 服务条款链接
        .termsOfServiceUrl("http://www.zhen.com/terms")
        // 文档版本号
        .version("2.0")
        .build();
  }
}

2.2 配置关键说明

配置项	作用说明
@EnableSwagger2	开启 Swagger2 自动扫描接口并生成文档的核心注解
Docket	每个 Docket 对应一个 API 分组，支持多分组配置（如订单、用户、商品等）
apis(RequestHandlerSelectors)	接口筛选规则，可按包路径、注解、类名等筛选（如 basePackage 指定包路径）
paths(PathSelectors)	路径筛选规则，可指定仅生成特定路径的接口文档
globalResponseMessage	全局统一配置响应信息（如 500 异常），避免重复定义
ApiInfo	文档元信息，用于展示文档标题、联系人、版本等基础信息

2.3 文档访问地址

Swagger2 默认可视化 UI 访问地址：http://{服务器IP}:{端口}/swagger-ui.html 示例：http://localhost:8080/swagger-ui.html

三、Swagger2 核心注解使用详解

Swagger2 通过注解丰富接口文档的描述信息，以下是常用注解的完整说明及使用示例。

3.1 控制器层注解

3.1.1 核心示例

import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.*;
import javax.servlet.http.HttpServletRequest;
/**
 * 订单导出控制器
 * 演示 Swagger2 核心注解的使用方式
 */
@RestController
@RequestMapping("/orders")
@Api(
    tags = "订单导出api",      // 接口标签（用于分组）
    produces = "application/json",  // 响应数据类型
    consumes = "application/json",  // 请求数据类型
    protocols = "http,https",       // 支持的协议
    hidden = false)                   // 是否隐藏该控制器
public class OrderExportController {
  /**
   * 订单导出任务 - 对象请求
   * @param req 订单详情请求参数
   * @param test 测试字段（忽略展示）
   * @param request HTTP 请求对象
   * @return EgResponse 通用响应结果
   * @throws Exception 异常信息
   */
  @ApiOperation(
      value = "订单导出任务提交",  // 接口名称
      notes = "根据订单编号、平台编码等条件提交订单导出任务，任务提交后异步处理，返回任务ID用于查询进度",  // 接口详细描述
      httpMethod = "GET",  // 请求方法
      produces = "application/json",  // 响应数据类型
      hidden = false,      // 是否隐藏接口
      response = EgResponse.class)  // 响应实体类型
  @ApiImplicitParams({
      @ApiImplicitParam(paramType = "query",  // 参数位置（path/query/body/header/form）
                        name = "test",       // 参数名称
                        value = "测试字段",   // 参数描述
                        required = true,     // 是否必填
                        dataType = "String", // 参数类型
                        example = "test123", // 参数示例值
                        allowEmptyValue = false), // 是否允许空值
      @ApiImplicitParam(paramType = "query",
                        name = "platformCode",
                        value = "平台编码",
                        required = true,
                        dataType = "String",
                        allowableValues = "70,80,90") // 允许的取值范围
  })
  @ApiResponses({
      @ApiResponse(code = 200, message = "请求成功，返回任务ID"), // 响应码+描述
      @ApiResponse(code = 400, message = "参数错误，如平台编码为空"),
      @ApiResponse(code = 500, message = "系统异常，导出任务提交失败")
  })
  @RequestMapping(value = "/doExportTaskToOperationOnObject.json", method = RequestMethod.GET)
  public EgResponse<OrderInfo> doExportTaskToOperationOnObject(
      OrderDetailRequest req,
      @ApiIgnore String test,  // 忽略该参数，不展示在文档中
      HttpServletRequest request) throws Exception {
    return EgResponse.success(new OrderInfo());
  }
}

3.1.2 控制器核心注解说明

注解	作用	核心属性
@Api	标记控制器，添加模块级说明	tags（分组标签）、hidden（是否隐藏）、produces/consumes（请求 / 响应类型）
@ApiOperation	标记接口方法，添加接口级说明	value（接口名称）、notes（详细描述）、httpMethod（请求方法）、response（响应类型）
@ApiImplicitParams	包裹多个 @ApiImplicitParam，描述多个参数	-
@ApiImplicitParam	描述单个参数信息	name（参数名）、paramType（参数位置）、required（是否必填）、example（示例值）
@ApiResponses	包裹多个 @ApiResponse，描述响应信息	-
@ApiResponse	描述单个响应码对应的信息	code（响应码）、message（描述）、response（响应实体）
@ApiIgnore	忽略指定元素（控制器、方法、参数），不生成到文档	-

3.2 实体类注解

3.2.1 请求实体示例

import io.swagger.annotations.ApiModelProperty;
import java.math.BigDecimal;
/**
 * 订单详情请求参数实体
 * 演示 @ApiModelProperty 注解的使用
 */
public class OrderDetailRequest {
  @ApiModelProperty(value = "平台编码", required = true, example = "70", position = 1)
  private String platformCode;
  @ApiModelProperty(value = "平台订单号", required = true, example = "sn20201029", position = 2)
  private String platformOrderSn;
  @ApiModelProperty(value = "订单状态", example = "0", allowableValues = "0,1,2,3,4", notes = "0-待支付，1-已支付，2-已发货，3-已完成，4-已取消", position = 3)
  private Integer status;
  @ApiModelProperty(value = "特殊字段", example = "0.00", hidden = true) // 隐藏该字段，不展示在文档中
  private BigDecimal special;
  @ApiModelProperty(value = "开始时间 格式：yyyy-MM-dd HH:mm:ss", example = "2024-01-01 00:00:00", position = 4)
  private String startTime;
  // 省略 getter/setter
}

3.2.2 响应实体示例

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
/**
 * 通用响应实体
 * 演示 @ApiModel 和 @ApiModelProperty 注解的使用
 */
@ApiModel(value = "EgResponse", description = "系统通用响应结果封装")
public class EgResponse<T> {
  @ApiModelProperty(value = "响应码", example = "200", notes = "200-成功，其他-失败")
  private String code;
  @ApiModelProperty(value = "响应描述", example = "操作成功")
  private String message;
  @ApiModelProperty(value = "响应数据", notes = "接口返回的业务数据，失败时为 null")
  private T data;
  // 通用成功响应方法
  public static <T> EgResponse<T> success(T data) {
    EgResponse<T> response = new EgResponse<>();
    response.setCode("200");
    response.setMessage("成功");
    response.setData(data);
    return response;
  }
  // 省略 getter/setter
}

3.2.3 实体类核心注解说明

注解	作用	核心属性
@ApiModel	标记实体类，添加实体级说明（主要用于请求 / 响应实体）	value（实体名称）、description（实体描述）
@ApiModelProperty	标记实体字段，添加字段级说明	value（字段描述）、required（是否必填）、example（示例值）、hidden（是否隐藏）、allowableValues（允许取值）

3.3 注解使用注意事项

1.@Api 注解非必须，Swagger 会自动扫描所有匹配的 Controller 生成文档，但建议添加以优化分组；

2.请求实体无需额外注解即可被 Swagger 识别，但通过 @ApiModelProperty 可丰富字段描述，提升文档可读性；

3.paramType 参数位置说明：

• path：路径参数（如 /orders/{id}）；
• query：查询参数（如 /orders?test=123）；
• body：请求体参数（JSON 格式）；
• header：请求头参数；
• form：表单参数；

4.example 属性在测试时会自动填充到 Swagger UI 的参数输入框，提升调试效率；

5.生产环境建议关闭 Swagger（通过 @Profile({"dev", "test"}) 注解仅在开发 / 测试环境启用），避免接口暴露。

四、Swagger2 使用进阶技巧

4.1 多分组配置

若系统模块较多（如订单、用户、商品），可配置多个 Docket 实现多分组：

@Bean
public Docket orderApi() {
  return new Docket(DocumentationType.SWAGGER_2)
      .groupName("订单模块")
      .apis(RequestHandlerSelectors.basePackage("com.zhen.export.order"))
      .paths(PathSelectors.ant("/orders/**"))
      // 其他配置...
      .build();
}
@Bean
public Docket userApi() {
  return new Docket(DocumentationType.SWAGGER_2)
      .groupName("用户模块")
      .apis(RequestHandlerSelectors.basePackage("com.zhen.export.user"))
      .paths(PathSelectors.ant("/users/**"))
      // 其他配置...
      .build();
}

4.2 生产环境关闭 Swagger

在配置类上添加 @Profile 注解，仅在开发 / 测试环境启用：

@Configuration
@EnableSwagger2
@Profile({"dev", "test"}) // 仅 dev、test 环境生效
public class SwaggerConfig {
  // 配置内容...
}

4.3 接口权限控制

结合 Spring Security，为 Swagger UI 添加登录验证，避免未授权访问：

@Override
protected void configure(HttpSecurity http) throws Exception {
  http.authorizeRequests()
      .antMatchers("/swagger-ui.html", "/v2/api-docs", "/swagger-resources/**").authenticated()
      .and()
      .formLogin()
      .and()
      .csrf().disable();
}

五、总结

通过 Spring Boot 集成 Swagger2，可快速实现 API 文档的自动化生成、可视化展示与在线调试，核心价值体现在以下三点：

1. 效率提升：文档与代码同步更新，无需人工维护，减少前后端沟通成本；
2. 易用性强：提供直观的 UI 界面，支持参数填充、一键调用，降低接口调试门槛；
3. 规范化：通过注解统一接口描述格式，使 API 文档更具可读性和专业性。

实际应用中，建议结合项目规模合理设计分组（如按业务模块划分），通过 @Profile 控制环境访问权限，并充分利用注解丰富文档信息，让 Swagger2 真正成为前后端协作的“桥梁”。

六、常见问题排查

6.1 无法访问 Swagger UI 界面（404 错误）

排查步骤：

1. 确认 springfox-swagger-ui 依赖已正确引入，无版本冲突；
2. 检查 Spring Boot 版本：2.6.x+ 需添加配置 spring.mvc.pathmatch.matching-strategy=ant_path_matcher；
3. 若使用权限框架（Spring Security/Shiro），需放行 Swagger 相关路径：

// Spring Security 示例配置
@Override
public void configure(WebSecurity web) throws Exception {
  web.ignoring()
      .antMatchers("/swagger-ui.html")
      .antMatchers("/v2/api-docs")
      .antMatchers("/swagger-resources/**")
      .antMatchers("/webjars/**");
}

4. 确认 @EnableSwagger2 注解已添加到配置类，且配置类被 Spring 扫描到。

6.2 接口未在文档中展示

排查步骤：

1. 检查 Docket 的 apis() 配置，确保接口所在包路径与 basePackage 一致；
2. 确认接口方法使用 @RequestMapping 或 @GetMapping 等注解（无映射注解的方法不会被扫描）；
3. 排查是否误加 @ApiIgnore 注解，或 @Api 的 hidden 属性设为 true；
4. 若为 POST 请求，检查是否缺少 @RequestBody 注解（未加注解的实体参数可能无法被识别）。

6.3 实体类字段未展示或展示异常

排查步骤：

1. 确认实体类字段已提供 getter/setter 方法（Swagger 通过反射获取字段信息）；
2. 检查 @ApiModelProperty 注解是否正确添加，避免属性名拼写错误；
3. 若字段类型为复杂对象（如 List、自定义实体），需确保关联类也被 Swagger 扫描到。

6.4 版本冲突导致启动失败

解决方案：

1. 优先使用稳定版本（如 2.9.2），避免使用过高或过低版本；
2. 若项目中存在 springfox-boot-starter 依赖，需移除单独的 springfox-swagger2 和 springfox-swagger-ui 依赖，避免重复引入；
3. 排除冲突依赖（以 Maven 为例）：

<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger2</artifactId>
  <version>2.9.2</version>
  <exclusions>
    <exclusion>
      <groupId>org.springframework.plugin</groupId>
      <artifactId>spring-plugin-core</artifactId>
    </exclusion>
  </exclusions>
</dependency>

七、扩展推荐

7.1 Swagger UI 美化

默认 UI 界面可替换为更美观的 swagger-bootstrap-ui，引入依赖即可使用：

<dependency>
  <groupId>com.github.xiaoymin</groupId>
  <artifactId>swagger-bootstrap-ui</artifactId>
  <version>1.9.6</version>
</dependency>

访问地址：http://{IP}:{端口}/doc.html

7.2 Swagger3 升级

Swagger3（OpenAPI 3.0）简化了配置，推荐新项目直接使用：

1.引入依赖：

<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-boot-starter</artifactId>
  <version>3.0.0</version>
</dependency>

2.核心变化：

• 移除 @EnableSwagger2 注解，依赖自动开启；
• 访问地址改为 http://{IP}:{端口}/swagger-ui/index.html；
• 支持更多 OpenAPI 规范特性，配置更简洁。