引入依赖:
首先导入Swagger所需的依赖:
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version> </dependency> <!-- 使用Swagger2最新版本2.9.2避免NumberFormatException错误要引入下列两个依赖 --> <dependency> <groupId>io.swagger</groupId> <artifactId>swagger-annotations</artifactId> <version>1.5.21</version> </dependency> <dependency> <groupId>io.swagger</groupId> <artifactId>swagger-models</artifactId> <version>1.5.21</version> </dependency>
Swagger配置:
在conf下新建一个Swagger.java配置类:
@Configuration @EnableSwagger2 public class SwaggerConfig { @Bean public Docket createRestApi(){ return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("com.winstar.system.controller")) .paths(PathSelectors.regex("/.*")) .build(); } private ApiInfo apiInfo(){ return new ApiInfoBuilder() .title("WinStar-Vehicle 电动车项目构建") .description("文档地址:https://www.cnblogs.com/xiaofanblog/") .termsOfServiceUrl("https://www.cnblogs.com/xiaofanblog/") .contact(new Contact("xiaofan","https://www.cnblogs.com/xiaofanblog/","[email protected]")) .version("v1.0") .build(); } }
以上就是Swagger全局配置信息,其中最需要注意的有以下几点:
Swagger生成API文档方式是通过扫描指定package下的请求映射类,根据映射接口生成API文档接口,所以关键是配置好扫描的接口类地址。
.apis(RequestHandlerSelectors.basePackage("com.winstar.system.controller"))扫描请求映射类package地址。一般用SpringMVC时,我们常把请求应映射类放在/controller/package下。
.paths(PathSelectors.regex("/.*"))扫描请求的路径,比如你想在Swagger中显示所有以/rest开头的接口地址(比如rest/save),就设置regex("/rest/.*"),这个.*就是匹配所有子级请求。这里我们配置的扫描所有请求。
查看PathSelectors类源码:
public class PathSelectors { private PathSelectors() { throw new UnsupportedOperationException(); } public static Predicate<String> any() { return Predicates.alwaysTrue(); } public static Predicate<String> none() { return Predicates.alwaysFalse(); } public static Predicate<String> regex(final String pathRegex) { return new Predicate<String>() { public boolean apply(String input) { return input.matches(pathRegex); } }; } public static Predicate<String> ant(final String antPattern) { return new Predicate<String>() { public boolean apply(String input) { AntPathMatcher matcher = new AntPathMatcher(); return matcher.match(antPattern, input); } }; } }
发现它能支持4中方式按照路径生成API文档:
1.任何路径都生成;2.任何路径都不生成;3.正则匹配路径;4.ant模式匹配。
上面我们就是配置的正则匹配路径,按照正则标准,Swagger扫描对应的API接口并生成文档。
既然用到了Swagger,那就必然遵循RESTful接口规范:
编写业务代码:
entity:
在entity下新建一个实体类对象User.java
@Entity @Data @Table(name = "user") public class User { /** * 主键id */ @Id @GeneratedValue private Integer id; /** * 姓名 */ private String name; /** * 账号 */ private String account; /** * 密码 */ @JsonIgnore private String password; /** * 盐 */ @JsonIgnore private String salt; /** * 是否禁用 0:否;1:是 */ private String forbidden; }
Result:
通常,Controller返回的数据都应该被封装在一个结果类中,目的是保证所有请求返回结果都有固定的响应格式,比如:状态码、状态信息、返回结果。所以我们简单封装一个结果类:R.java
/** * HTTP返回得对象模型 * @param <T> */ @Data @JsonInclude(JsonInclude.Include.NON_NULL) public class R<T> { /** * 状态码 */ private Integer code; /** * 提示信息 */ private String msg; /** * 具体数据 */ private T data; }
controller:
在controller下新建控制类 UserController.java,编写常见的CRUD业务场景:
@Slf4j @RestController @RequestMapping("/api/v1/sys") @Api(value = "UserController",tags = {"用户管理"}) public class UserController { @Autowired private UserService userService; /** * 新增用户 * @param userFrom * @param bindingResult * @return */ @ApiOperation(value = "新增用户信息") @RequiresPermissions("sys:user:insert") @PostMapping("/saveUser") public R saveUser(@Valid @RequestBody UserFrom userFrom, BindingResult bindingResult){ if(bindingResult.hasErrors()){ log.error("【新增用户】参数不正确:userFrom={}"+ userFrom); throw new SystemException(REnum.PARAM_ERROR.getCode(),bindingResult.getFieldError().getDefaultMessage()); } return userService.saveUser(userFrom); } /** * 查询用户列表 * @param page * @param size * @param name * @return */ @ApiOperation(value = "查询用户列表") @RequiresPermissions("sys:user:list") @GetMapping("/selectUserList") public R selectUserList(@RequestParam(value = "page", defaultValue = "0") Integer page, @RequestParam(value = "size", defaultValue = "10") Integer size, @RequestParam(value = "name",defaultValue = "") String name){ PageRequest pageRequest = new PageRequest(page,size); return userService.selectUserList(name,pageRequest); } /** * 查询用户详情 * @param id * @return */ @ApiOperation(value = "查询用户详情") @RequiresPermissions("sys:user:detail") @GetMapping("/selectUserDetail") public R selectUserDetail(@RequestParam(value = "id",required = false) Integer id){ Assert.isNull(id,"id不能为空"); return userService.selectUserDetail(id); } /** * 更新用户 * @param userFrom * @param bindingResult * @return */ @ApiOperation(value = "更新用户信息") @RequiresPermissions("sys:user:update") @PutMapping("/updateUser") public R updateUser(@Valid @RequestBody UserFrom userFrom, BindingResult bindingResult){ Assert.isNull(userFrom.getId(),"id不能为空"); if(bindingResult.hasErrors()){ log.error("【更新用户】参数不正确:userFrom = {}"+ userFrom); throw new SystemException(REnum.PARAM_ERROR.getCode(),bindingResult.getFieldError().getDefaultMessage()); } return userService.updateUser(userFrom); } /** * 删除用户 * @param id * @return */ @ApiOperation(value = "删除用户信息") @RequiresPermissions("sys:user:delete") @DeleteMapping("/deleteUser/{id}") public R deleteUser(@PathVariable Integer id){ return userService.delectUser(id); } }
测试:
启动项目,访问localhost:8080/swagger-ui.html:
具体Swagger注解,请参考Swagger 注解篇:https://www.cnblogs.com/xiaofanblog/p/11430267.html