玩转 SpringBoot 2 快速整合 | 丝袜哥(Swagger)

概述

首先让我引用 Swagger 官方的介绍：

Design is the foundation of your API development. Swagger makes API design a breeze, with easy-to-use tools for developers, architects, and product owners.

设计是API开发的基础。Swagger使API设计变得轻而易举，为开发人员，架构师和产品所有者提供了易于使用的工具。

作为一个后端开发者，你是否为开发完 API 接口后为写文档而烦恼、当 App 开发人员或前端开发人员看不懂的你写的接口文档，你还得去给他们讲一遍怎么使用而烦恼。

使用 Swagger 这些烦恼统统的消失，Swagger一个集预览和测试于一身的在线可视化 RESTful 风格的 Web 服务框架。

闲话少说，直接开整！

基础配置和 API 接口开发

第一步：先引入Swagger starter 依赖到 pom 文件中。我们这里采用2.7.0 版本

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.7.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.7.0</version>
</dependency>

还有一点需要注意的是必须引入 Spring Boot Web starter 依赖。

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

第二步：编写 RESTful API 服务：一个用户的增删改查。

public class User {
 
        private String name;
        private Integer age;
        //......省略get and set方法
}

定义用户 RESTFull API 服务 Controller。

@RestController()
@RequestMapping("/user")
public class UserController {
//......
}

在 RESTFull API 服务 Controller 添加根据 id查询用户的接口

    /**
     * 根据用户id 查询用户
     * @return
     */
    @GetMapping("/{id}")
    public User get(@PathVariable(name = "id") Long id){
        User user = new User();
        user.setName("lijunkui");
        user.setAge(18);
        log.info("springboot查询用户成功："+"id:{}",id);
        return user;
    }

定义添加用户接口。

/**
     * 添加用户
     */
    @PostMapping()
    public void add(User user){
        log.info("springboot添加用户成功："+"name:{},age:{}",user.getName(),user.getAge());
    }

定义更新用户接口。

 /**
     * 全部更新
     * @param user
     */
    @PutMapping()
    public void updatePut(User user){
        log.info("springboot Put 修改用户成功："+"name:{},age:{}",user.getName(),user.getAge());
     }

定义 局部更新用户接口。

 /**
     * 局部更新
     */
    public void updatePatch(@PathVariable("name") String name){
        log.info("springboot Patch 修改用户成功："+"name:{}",name);
    }

定义删除用户接口。

  /**
     * 删除用户
     */
    @DeleteMapping("/{id}")
    public void delete(@PathVariable("id") Long id){
        User user = new User();
        user.setName("lijunkui");
        user.setAge(18);
        log.info("springboot 删除用户成功："+"id:{}",id);
    }

定义根据 json 数据更新用户接口。

 /**
     * 根据requestBody 更新用户信息
     * @param user
     * @return
     */
    @PostMapping("/updateUserByRequestBody")
    public void updateUserByRequestBody(@RequestBody User user){
        log.info("updateUserByRequestBody 修改用户成功："+"name:{},age:{}",user.getName(),user.getAge());
    }

第三步：编写 Swagger 的Config配置类

//让Spring来加载该类配置
@Configuration
//是否禁用swagger 的配置
@ConditionalOnProperty(prefix = "swagger",value = {"enable"},havingValue = "true")
//启用Swagger2
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket alipayApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("简单用户管理API接口文档")
                .apiInfo(apiInfo())
                .select()
 //扫描配置 classpath 路径配置 Swagger注解下的 Api文档。 .apis(RequestHandlerSelectors.basePackage("com.ljk.springBootLearn.users"))
                .paths(PathSelectors.any()).build();
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("SprignBoot学习专栏")
                .description("集成swagger")
                .termsOfServiceUrl("https://blog.csdn.net/ljk126wy")
                //创建人
                .contact(new Contact("桌前明月", "http://www.baidu.com", ""))
                //版本
                .version("1.0")
                //API 描述
                .description("简单介绍如有问题还望指正")//
                .build();
    }
}

我来简单介绍一下 Swagger 的配置类中方法使用介绍。

每一组 Controller 的 Api 都对应一个 Docket 配置 ，如果有多个组 Api 就应该配置多个Docket 的 Bean。

Docket.groupName(String name)：配置接口分组的名称，name为分组的名称。对应下图中红色框中的信息

apiInfo(ApiInfo apiInfo ) 配置Api 文档的一些公共的描述信息，对应下图中红色框中的信息。

paths()：配置需要显示具体 Api 的路径。

我们通过PathSelectors类的4个方法来进行判断

1. PathSelectors.any(): 所有的api都显示
2. PathSelectors.none(): 所有的路径都不显示
3. PathSelectors.regex(String pathRegex): 按照String的matches方法进行匹配。例如：PathSelectors.regex("/user/*")
4. PathSelectors.ant(String antPattern): 按照Spring的AntPathMatcher提供的match方法进行匹配 例如：PathSelectors.ant("/user/**")

AntPathMatcher.match(String pattern, String path) 可以做URLs匹配，规则如下

？匹配一个字符

*匹配0个或多个字符

** 匹配0个或多个目录

第四步：在application.properties 或 application.yml中添加配置信息。
在application.properties 配置信息如下：

server.port=8080
server.servlet.context-path=/sbe
swagger.enable = true
application.yml 配置内容如下：

application.yml 配置信息如下：

server:
  port: 8080 #游览器访问项目端口号
  servlet:
    context-path:/sbe #游览器访问项目的名称
swagger:
  enable: true

需要注意的是application.properties 或 application.yml 只能存在一个，swagger.enable =
true表示是否使用Swagger的的功能。主要用于生产环境和开发环境的配置。切记生产环境要配置成false。

到目前为止SpringBoot 整合 Swagger 基础部分搭建完毕！接下来让我们今天的重点 Swagger 配置注解。

Swagger 注解使用实战

@Api ： 说明接口类的作用。

@Api(tags ="用户管理")
@RestController()
@RequestMapping("/user")
public class UserController {
}

访问 Swagger UI 界面如下：

@ApiOperation： 用在方法上 说明方法的作用。

    @ApiOperation(value="根据id获取用户信息")
    @GetMapping("/{id}")
    public User get(@PathVariable(name = "id") Long id){
      //省略逻辑代码
    }

访问 Swagger UI 界面如下：

@ApiImplicitParam： 方法中参数的说明

 /**
     * 根据用户id 查询用户
     * @return
     */
    @ApiImplicitParam(paramType= "path", name = "id", value = "用户id", required = true, dataType = "Long")
    @GetMapping("/{id}")
    public User get(@PathVariable(name = "id") Long id){
       //省略逻辑代码
    }

访问 Swagger UI 界面如下：

@ApiImplicitParams(): 配置多个ApiImplicitParam

    @ApiImplicitParams({

@ApiImplicitParam(name="name",value="用户名",dataType="string", required = true, paramType = "form",example="ljk"),
@ApiImplicitParam(name="age",value="用户年龄",dataType="int", paramType = "form")})

    @PostMapping()

    public void add(User user){
      //省略逻辑代码
    }

访问 Swagger UI 界面如下：

@ApiModel: 描述返回实体类信息

@ApiModel(value="user对象",description="用户对象user")
public class User {
}

@ApiModelProperty: 描述返回实体类属性的信息

public class User {
    @ApiModelProperty(value="用户名",name="name",example="xingguo")
    private String name;
    @ApiModelProperty(value="年龄1",name="age",required=true)
    private Integer age;
}

访问 Swagger UI 界面如下：

@ApiResponse： 错误相应信息描述
@ApiResponses: 描述多个错误信息

    @GetMapping("/{id}")
    @ApiResponses({ @ApiResponse(code = 400, message = "请求无效 (Bad request)") })
    public User get(@PathVariable(name = "id") Long id){
     //省略逻辑代码
    }

访问 Swagger UI 界面如下：

@ApiParam： 用于声明通过request接受的参数。
@ApiIgnore(): 忽略的字段不显示在api文档中。

public void logon(
@ApiParam(name="loginName",value="登录名称",required=true)
@RequestParam String loginName,
@ApiParam(name="password",value="密码",required=true)
@RequestParam String password, 
@ApiIgnore()Model model,HttpServletRequest request){
}

启动 SpringBoot 项目访问：localhost:8080/sbe/swagger-ui.html 如下图所示：

我们可以在如下图中的 name 和 age 输入框中输入内容并进行测试，这里就不一个个进行测试啦。

小结

SpringBoot 整合 Swagger 需要通过SpringBoot Java Config的方式配置 Api 接口扫描的路径、接口组介绍、接口版本、接口描述等信息。接下来就是 Swagger 的具体配置注解，常用的配置注解如下：

@Api ：说明接口类的作用。

@ApiOperation：用在方法上 说明方法的作用。

@ApiImplicitParam：方法中参数的说明。

@ApiImplicitParams()：配置多个 ApiImplicitParam

@ApiModel：描述返回实体类信息。

@ApiModelProperty：描述返回实体类属性的信息。

@ApiResponse：错误相应信息描述。

@ApiResponses：描述多个错误信息。

@ApiParam：用于声明通过request接受的参数。

@ApiIgnore()：忽略的字段不显示在api文档中。

如果你还没有操作过，可以跟着博客敲一遍哈！

代码示例

文中的代码可以参考我的 GitHub 仓库名称 springbootexamples 中的 spring-boot-2.x-swagger 进行查看

GitHub：https://github.com/zhuoqianmi...

示例程序环境版本：

SpringBoot Version：2.1.0.RELEASE
SpringMVC Version：5.1.2RELEASE
Maven Version：3.2.5
JDK Version：1.8.0_144