1. 引言在前后端分离的开发模式下接口文档的维护一直是个痛点。Swagger 作为一款流行的 API 文档工具能够根据代码自动生成接口文档并提供在线调试功能极大提升了团队协作效率。本文将通过丰富的代码实例带你从零开始掌握 Swagger 的集成与使用。2. Swagger 简介Swagger 是一套围绕 OpenAPI 规范构建的开源工具集它可以帮助开发者设计、构建、记录和使用 REST API。其核心价值在于自动生成文档通过注解即可生成接口文档无需手动维护。在线调试直接在文档页面发送请求验证接口正确性。多语言支持支持 Java、Python、Node.js 等多种主流语言。3. Spring Boot 集成 Swagger下面以 Spring Boot 项目为例演示如何快速集成 Swagger。首先在pom.xml中添加依赖dependency groupIdio.springfox/groupId artifactIdspringfox-boot-starter/artifactId version3.0.0/version /dependency然后创建 Swagger 配置类定义文档基本信息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; Configuration public class SwaggerConfig { Bean public Docket createRestApi() { return new Docket(DocumentationType.OAS_30) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage(com.example.controller)) .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title(用户管理 API) .description(用户管理系统的接口文档) .version(1.0.0) .build(); } }4. 常用注解详解Swagger 提供了一系列注解用于描述接口的详细信息。下面通过一个用户控制器实例展示常用注解的用法import io.swagger.annotations.Api; import io.swagger.annotations.ApiOperation; import io.swagger.annotations.ApiParam; import org.springframework.web.bind.annotation.*; Api(tags 用户管理接口) RestController RequestMapping(/api/users) public class UserController { ApiOperation(获取用户列表) GetMapping public ResultListUser listUsers() { // 业务逻辑省略 return Result.success(userService.list()); } ApiOperation(根据 ID 查询用户) GetMapping(/{id}) public ResultUser getUserById( ApiParam(value 用户 ID, required true) PathVariable Long id) { return Result.success(userService.getById(id)); } ApiOperation(创建用户) PostMapping public ResultUser createUser( ApiParam(value 用户信息, required true) RequestBody User user) { return Result.success(userService.create(user)); } ApiOperation(更新用户) PutMapping(/{id}) public ResultUser updateUser( ApiParam(value 用户 ID, required true) PathVariable Long id, ApiParam(value 用户信息, required true) RequestBody User user) { return Result.success(userService.update(id, user)); } ApiOperation(删除用户) DeleteMapping(/{id}) public ResultVoid deleteUser( ApiParam(value 用户 ID, required true) PathVariable Long id) { userService.delete(id); return Result.success(); } }其中Api用于描述控制器类ApiOperation描述接口功能ApiParam描述参数信息。启动项目后访问http://localhost:8080/swagger-ui/index.html即可查看文档页面。5. 实体类文档描述为了让文档更完整还需要对实体类进行描述。使用ApiModel和ApiModelProperty注解import io.swagger.annotations.ApiModel; import io.swagger.annotations.ApiModelProperty; ApiModel(用户实体) public class User { ApiModelProperty(value 用户 ID, example 1) private Long id; ApiModelProperty(value 用户名, example zhangsan) private String username; ApiModelProperty(value 邮箱, example zhangsanexample.com) private String email; // 省略 getter 和 setter }6. 统一响应结构实际项目中接口通常返回统一的响应结构。为了让文档更规范可以这样定义import io.swagger.annotations.ApiModel; import io.swagger.annotations.ApiModelProperty; ApiModel(统一响应结果) public class ResultT { ApiModelProperty(value 状态码, example 200) private Integer code; ApiModelProperty(value 提示信息, example 操作成功) private String message; ApiModelProperty(value 数据) private T data; public static T ResultT success() { return success(null); } public static T ResultT success(T data) { ResultT result new Result(); result.setCode(200); result.setMessage(操作成功); result.setData(data); return result; } // 省略 getter 和 setter }7. 分组配置当项目接口较多时可以按模块分组展示。在配置类中创建多个Docket实例Configuration public class SwaggerConfig { Bean public Docket userApi() { return new Docket(DocumentationType.OAS_30) .groupName(用户模块) .select() .apis(RequestHandlerSelectors.basePackage(com.example.controller.user)) .build(); } Bean public Docket orderApi() { return new Docket(DocumentationType.OAS_30) .groupName(订单模块) .select() .apis(RequestHandlerSelectors.basePackage(com.example.controller.order)) .build(); } }8. 常见问题与解决在集成过程中可能会遇到以下常见问题启动报错检查依赖版本是否与 Spring Boot 版本兼容必要时升级或降级。文档页面 404确认是否放行了 Swagger 相关路径或在配置中排除拦截。注解不生效检查是否引入了正确的io.swagger.annotations包。9. 总结本文通过完整的代码实例介绍了 Swagger 在 Spring Boot 项目中的集成方法、常用注解、分组配置以及常见问题。掌握这些内容后你就能为项目快速生成规范、可调试的接口文档提升开发与协作效率。