关于SpringBoot整合Swagger2的总结

一. Swagger2简介

相信大家都知道SpringBoot，下面谈一下什么是Swagger2，以及它的作用。

接口文档生成工具Swagger2是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。

作用：

　　1. 接口的文档在线自动生成。

　　2. 功能测试。

二.整合步骤

1. 引入依赖

在pom.xml文件中添加以下依赖：

<!--依赖管理 -->
    <dependencies>
        <dependency> <!--添加Web依赖 -->
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency><!--添加Swagger依赖 -->
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.7.0</version>
        </dependency>
        <dependency><!--添加Swagger-UI依赖 -->
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.7.0</version>
        </dependency>
        <dependency> <!--添加热部署依赖 -->
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-devtools</artifactId>
        </dependency>
        <dependency><!--添加Test依赖 -->
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>

2. 添加配置

/**
 * Created by TAO on 2019-07-03.
 */
@Configuration //标记配置类
@EnableSwagger2 //开启在线接口文档
public class Swagger2Config {
    /**
     * 添加摘要信息(Docket)
     */
    @Bean
    public Docket controllerApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(new ApiInfoBuilder()
                        .title("标题：某公司_用户信息管理系统_接口文档")
                        .description("描述：用于管理集团旗下公司的人员信息,具体包括XXX,XXX模块...")
                        .contact(new Contact("一只袜子", null, null))
                        .version("版本号:1.0")
                        .build())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.app.hisun.controller"))
                .paths(PathSelectors.any())
                .build();
    }
}

3.编写接口文档

   Swagger2 基本使用：

• @Api 描述类/接口的主要用途
• @ApiOperation 描述方法用途
• @ApiImplicitParam 描述方法的参数
• @ApiImplicitParams 描述方法的参数(Multi-Params)
• @ApiIgnore 忽略某类/方法/参数的文档

  Swagger2 使用注解来编写文档：

  Swagger2编写接口文档相当简单，只需要在控制层（Controller）添加注解来描述接口信息即可。例如：

  /**
   * Created by TAO on 2019-07-03.
   */
  @Api("用户信息管理")
  @RestController
  @RequestMapping("/user/*")
  public class UserController {
  
      private final static List<User> userList = new ArrayList<>();
  
      {
          userList.add(new User("1", "admin", "123456"));
          userList.add(new User("2", "jacks", "111111"));
      }
  
      @ApiOperation("获取列表")
      @GetMapping("list")
      public List userList() {
          return userList;
      }
  
      @ApiOperation("新增用户")
      @PostMapping("save")
      public boolean save(User user) {
          return userList.add(user);
      }
  
      @ApiOperation("更新用户")
      @ApiImplicitParam(name = "user", value = "单个用户信息", dataType = "User")
      @PutMapping("update")
      public boolean update(User user) {
          return userList.remove(user) && userList.add(user);
      }
  
      @ApiOperation("批量删除")
      @ApiImplicitParam(name = "users", value = "N个用户信息", dataType = "List<User>")
      @DeleteMapping("delete")
      public boolean delete(@RequestBody List<User> users) {
          return userList.removeAll(users);
      }
  }

  /**
   * Created by TAO on 2019-07-03.
   */
  public class User {
      private String userId;
      private String username;
      private String password;
  
      public User() {
  
      }
  
      public User(String userId, String username, String password) {
          this.userId = userId;
          this.username = username;
          this.password = password;
      }
  
      @Override
      public boolean equals(Object o) {
          if (this == o) {
              return true;
          }
          if (o == null || getClass() != o.getClass()) {
              return false;
          }
  
          User user = (User) o;
  
          return userId != null ? userId.equals(user.userId) : user.userId == null;
      }
  
      @Override
      public int hashCode() {
          int result = userId != null ? userId.hashCode() : 0;
          result = 31 * result + (username != null ? username.hashCode() : 0);
          result = 31 * result + (password != null ? password.hashCode() : 0);
          return result;
      }
  
      public String getUserId() {
          return userId;
      }
  
      public void setUserId(String userId) {
          this.userId = userId;
      }
  
      public String getUsername() {
          return username;
      }
  
      public void setUsername(String username) {
          this.username = username;
      }
  
      public String getPassword() {
          return password;
      }
  
      public void setPassword(String password) {
          this.password = password;
      }
  }

  4.查阅接口文档

          编写文档完成之后，启动当前项目，在浏览器输入路径：

          http://localhost:8080/swagger-ui.html

          进入swagger2界面后可以查看接口文档以及进行接口测试等各种操作。如：

 未完待续。。。