SpringBoot整合第三方Swagger Starter实现接口文档自动化

结果与目标：一键启用API文档

使用本方案的目标是在不修改任何Java Config代码的前提下，完成以下操作：

• 自动生成符合RestFul风格的API文档界面。
• 支持在线调试接口，同步更新接口定义。
• 实现多模块/分组的包路径扫描隔离。
• 配置简单的账号密码登录保护（可选）。

准备条件

确保项目基于SpringBoot构建，且具备Maven或Gradle依赖管理工具。若使用Gradle，需将下述Maven坐标转换为对应的implementation语法。

真实操作顺序

第1步：引入第三方Starter依赖

为了简化配置，我们采用非官方但广泛使用的第三方库com.battcn提供的Starter。它屏蔽了底层复杂的配置类加载过程。

在 pom.xml 中添加依赖：

<!-- Swagger 第三方 Starter -->
<dependency>
    <groupId>com.battcn</groupId>
    <artifactId>swagger-spring-boot-starter</artifactId>
    <version>2.1.5-RELEASE</version>
</dependency>

注意：此版本较旧，若你的SpringBoot版本较高（如2.x后期或3.x），可能需要寻找更新的兼容包或改用springdoc-openapi。此处以原文提供的稳定配置为例。

第2步：配置 application.yml

在 application.yml 中直接定义 swagger 节点。以下是包含分组、全局Token验证及账号密码保护的完整配置示例：

spring:
  swagger:
    enabled: true                  # 开启Swagger
    title: "星空小屋 - 文章微服务接口"
    description: "文章微服务相关接口说明"
    version: "1.0.0-SNAPSHOT"
    contact:
      name: "维护者名称"
      email: "admin@example.com"
    base-package: com.example.controller # 默认全扫描，可指定特定包
    
    # 全局参数配置，例如统一添加Authorization Header
    global-operation-parameters:
      - description: 'Bearer Token信息'
        modelRef: 'string'
        name: 'Authorization'
        parameter-type: 'header'
        required: true

    # 分组配置：按业务模块隔离API展示
    groups:
      basic-group:
        base-package: com.example.controller.basic
      system-group:
        base-package: com.example.controller.system

    # 安全配置：开启访问保护
    security:
      filter-plugin: true  # 启用Basic Auth
      username: root       # 文档访问账号
      password: root       # 文档访问密码

关键参数说明：

• base-package：控制扫描Controller的范围，默认为全扫描。若启用了groups，建议在各组内单独指定base-package以提高效率。
• global-operation-parameters：适合配置所有接口共用的Header参数（如Token），避免在每个接口重复声明。

第3步：处理Interceptor拦截器冲突

如果项目中已存在自定义的 HandlerInterceptor 或 Spring Security 过滤器，必须确保放行Swagger相关的静态资源与API地址，否则将无法访问文档页面。

需在拦截器 preHandle 方法中忽略以下路径：

• /swagger-ui.html：UI入口。
• /static/**：静态资源（CSS/JS）。
• /swagger-resources/**：Swagger资源配置。
• /v2/api-docs：核心API JSON数据源。
• /**/error：错误页。

第4步：编写接口代码并添加注解

在Controller层使用注解描述API细节。以下是核心注解对照表：

类级别：@Api

标记Controller类，用于分组标题和描述。

@Api(tags = "文章管理", value = "ArticleController")
@RestController
@RequestMapping("/article")
public class ArticleController { ... }

方法级别：@ApiOperation

标记具体接口方法，显示在文档中的动作。

@ApiOperation(value = "获取文章详情", notes = "根据ID查询单篇文章")
@GetMapping("/{id}")
public Result getDetail(@PathVariable Long id) { ... }

请求参数对象：@ApiModel & @ApiModelProperty

当接口接收复杂JSON体时，使用这两个注解定义字段含义。

@ApiModel(value = "ArticleREQ", description = "文章请求实体")
public class ArticleREQ {
    @ApiModelProperty(value = "文章标题", required = true)
    private String title;

    @ApiModelProperty(value = "分类ID", hidden = false)
    private Long categoryId;
}

单个参数描述：@ApiImplicitParam

适用于非对象的简单参数，如Path变量或Query参数。

@ApiImplicitParams({
    @ApiImplicitParam(name = "page", value = "页码", dataType = "int", paramType = "query"),
    @ApiImplicitParam(name = "size", value = "每页条数", dataType = "int", paramType = "query")
})
@GetMapping("/list")
public Result list(int page, int size) { ... }

第5步：运行与测试

启动SpringBoot应用后，在浏览器访问：http://localhost:端口号/swagger-ui.html。

若配置了security.filter-plugin，首次进入需输入配置的账号密码（如 root/root）。登录后即可看到按分组整理的API列表。

排错与支持

• 404 Not Found：检查Interceptor是否拦截了 /v2/api-docs 或 /swagger-ui.html，请将其加入白名单。
• 中文乱码：通常由字符编码设置引起，确保Tomcat或服务端统一使用UTF-8编码。
• 注解未生效：检查Controller所在的包是否在 base-package 扫描范围内。

总结

通过集成 battcn-swagger-spring-boot-starter，开发者可以将SpringBoot的API文档配置从“代码模式”切换到“YAML模式”。这种轻量级方案特别适合中小型项目或追求极简配置的场景。配合标准的 @Api 系列注解，即可快速构建清晰、可交互的在线接口文档。

以上就是SpringBoot使用Swagger Starter实现接口文档自动化的详细内容，更多关于SpringBoot集成的资料请关注本站其它相关文章！