Spring boot 整合 Swagger

引入依赖：

首先导入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/","1320237548@qq.com"))
                .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