本文共 4865 字，大约阅读时间需要 16 分钟。
随着前后端分离式开发的流行，传统的 JSP 开发逐渐被 Vue、Angular、React 等前端框架取代，而后端则通过接口返回 JSON 数据供前端调用，省去了视图跳转的复杂过程。然而，这也带来了一个新的挑战：后端程序员需要撰写接口文档来指导前端开发人员，这无疑是一项耗时费力的工作。
Swagger（现已更名为 OpenAPI）是一款强大的接口文档生成工具，它能够根据程序代码自动生成接口文档。通过 Swagger，我们可以轻松创建一个在线接口文档，方便前端开发人员快速了解和使用后端接口。以下将详细介绍如何在 Spring Boot 2.x 项目中整合 Swagger。
首先，我们需要在项目中引入 Swagger 的 Maven 依赖包。Swagger 提供了两套主要的版本：Swagger 1.5 和 Swagger 2.0。为了与 Spring Boot 2.x 的版本兼容，我们选择 Swagger 2.x 的最新版本。
io.springfox springfox-swagger2 3.0.0 io.springfox springfox-swagger-ui 3.0.0
此外，由于 Swagger 依赖较多，为了解决某些运行时异常，可以选择以下版本：
io.swagger swagger-annotations 1.5.21 io.swagger swagger-annotations io.swagger swagger-models 1.5.21 io.swagger swagger-models io.springfox springfox-swagger-ui 2.9.2
在引入 Swagger 依赖后，我们需要通过注解开启 Swagger 功能。创建一个新的配置类，并在类上注解 @EnableSwagger2。
@Configuration@EnableSwagger2public class SwaggerConfig { // 可以添加多个 Swagger 文档配置，用于不同的接口分组} 启用 Swagger 后，访问 http://localhost:8080/swagger-ui.html 即可查看接口文档页面。
Swagger 生成的接口文档主要包含以下四个部分：
@ApiTags 注解，可以为接口分组，方便管理和查找。apiInfo() 方法配置分组的描述、联系方式等信息。@ApiOperation 注解添加详细的描述，包括接口标题和说明。@ApiModel 和 @ApiModelProperty 注解，可以为实体类添加详细的文档描述。为了实现自定义分组，我们需要在配置类中提供一个 Docket 实例到 IOC 容器中。以下是一个简单的分组配置示例：
@Configuration@EnableSwagger2public class SwaggerConfig { @Bean public Docket docket() { return new Docket(DocumentationType.SWAGGER_2) .groupName("张涵哲的分组"); }} 此外，如果需要多个分组，可以通过在配置类中定义多个 Docket 实例：
@Configuration@EnableSwagger2public class SwaggerConfig { @Bean public Docket mainGroup() { return new Docket(DocumentationType.SWAGGER_2) .groupName("主分组"); } @Bean public Docket subGroup() { return new Docket(DocumentationType.SWAGGER_2) .groupName("子分组"); }} 除了分组名称之外，我们还可以为每个分组添加描述信息。以下是一个完整的分组配置示例：
@Configuration@EnableSwagger2public class SwaggerConfig { @Bean public Docket mainGroup() { return new Docket(DocumentationType.SWAGGER_2) .groupName("主分组") .apiInfo(apiInfo()); } private ApiInfo apiInfo() { Contact contact = new Contact("张涵哲", "http://blog.hanzhe.club", null); return new ApiInfo( "主分组 API 文档", "张涵哲的 API 文档", "1.0.0", null, contact, null, " Swagger 2.0 文档", new ArrayList<>()); }} 此外，Swagger 还支持通过 select() 方法筛选接口。例如，根据包路径或路径来过滤接口：
@Configuration@EnableSwagger2public class SwaggerConfig { @Bean public Docket mainGroup() { return new Docket(DocumentationType.SWAGGER_2) .groupName("主分组") .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("com.example.controller")) .build(); } private ApiInfo apiInfo() { // 同上 }} 为了让接口文档更加详细，我们可以使用以下注解：
例如，以下是一个完整的 UserController 配置：
@RestController@RequestMapping("/user")@Api(tags = "用户接口文档")public class UserController { @GetMapping("/") @ApiOperation(value = "查询所有用户", notes = "获取用户列表") public R getUserList() { // 业务逻辑 } @PostMapping("/") @ApiOperation(value = "添加新用户", notes = "提交用户信息进行添加") public R addUser(@RequestBody UserBean user) { // 业务逻辑 } @PutMapping("/{id}") @ApiOperation(value = "更新用户信息", notes = "路径传入 ID，json 传输修改信息") public R updateUser(@PathVariable("id") Long id, @RequestBody UserBean user) { // 业务逻辑 } @DeleteMapping("/{id}") @ApiOperation(value = "删除用户信息", notes = "路径传入 ID 进行删除") public R deleteUser(@ApiParam("删除的目标 ID") @PathVariable("id") Long id) { // 业务逻辑 }} 为了让实体类信息也出现在文档中，我们可以使用以下注解：
例如，以下是一个简单的 UserBean 配置：
@Data@NoArgsConstructor@AllArgsConstructor@ApiModel("员工实体类")public class UserBean { @ApiModelProperty("员工 ID，用来识别员工的唯一表示，不可重复。") private Long id; @ApiModelProperty("员工姓名") private String name; @ApiModelProperty("员工年龄") private Integer age;} 通过以上配置，您可以轻松生成和管理接口文档，提升后端与前端的协作效率。
转载地址：http://htxuz.baihongyu.com/