Swagger快速入门教程笔记 (3)

跨组显示接口

之前有说过，Swagger 默认是按照每个 Controller 为一个分组显示接口的，那么如果我们其中一个 Controlle 执行时需要另个 Controller 的某个接口配合，这时我们当前分组就要支持显示其他分组信息。

**1. **员工的分组接口除了本身的增删改查之外还要查询携带查询所有部门信息：

@Api(tags = "部门接口") @RestController @RequestMapping("/dept") public class DeptController { @GetMapping("http://www.likecs.com/") // tags 是一个数组，可以制定多个分组同时显示 @ApiOperation( value = "查询所有部门", tags = {"部门接口", "员工接口"}) public void getList(){ } // .... 省略其他接口 }

如下图所示：

通过已有的接口新建一个分组

除了接口跨分组显示之外，还可以在多个不同的接口中指向同一个不存在的分组，Swagger 会新建一个分组来展示这些接口信息。

@Api(tags = "员工接口") @RestController @RequestMapping("/user") public class UserController { @DeleteMapping("/{id}") @ApiOperation(value = "通过ID删除user信息", notes = "路径传入ID进行删除", tags = "删除操作相关接口") public R deleteUser(@ApiParam("删除的目标ID")@PathVariable("id") Long id){ ... } } @Api(tags = "部门接口") @RestController @RequestMapping("/dept") public class DeptController { @DeleteMapping("/{id}") @ApiOperation(value = "通过ID删除部门", tags = "删除操作相关接口") public void deleteUser(@ApiParam("删除的目标ID")@PathVariable("id") Long id){ } }

实体类信息配置

我们在开始的时候就 Swagger 接口文档由 分组，分组描述信息，接口信息，实体类信息 四部分组成，前三种我们已经使用过了，接下来我们就要学习使用配置类信息

当我们需要完成类似添加操作的时候，如果需要的参数过多，使用 @ApiParam 注解就会太过臃肿，直接封装为实体类又要解释每个字段都是干什么的，是什么类型，接口显示也过于繁琐，所以我们可以将实体类直接显示在文档中，当时用到该实体类时在底部翻找属性对应参数即可，一个实体类可以对应 N 多个接口，一劳永逸

实体类的配置

配置实体类十分的简单，只需要使用两个注解就可以完成基本操作：

注解 作用
@ApiModel()   实体类名称  
@ApiModelProperty()   实体类中每个字段代表的含义解释  
@Data @NoArgsConstructor @AllArgsConstructor @ApiModel("员工实体类") public class UserBean { @ApiModelProperty("员工ID，用来识别员工的唯一表示，不可重复。") private Long id; @ApiModelProperty("员工姓名") private String name; @ApiModelProperty("员工年龄") private Integer age; }

效果如图所示：