在Spring Boot中使用Swagger2

• Maven依赖
• Swagger配置
• 演示代码

1. Maven依赖

首先，导入相关依赖

<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>

2. Swagger配置

其次，对Swagger进行一些简单的配置

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
            	//初始化并返回一个API选择构造器
                .select()
                // 扫描所有有注解的api
 .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                // 扫描所有 .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
            	//创建该API的基本信息
                .build().apiInfo(new ApiInfoBuilder()
                        .title("your title")
                        .description("your description")
                        .version("your version")
                        .contact(new Contact("your name","your blogUrl","your email"))
                        .license("your License")
                        .licenseUrl("your licenseUrl")
                        .build());
    }
}

• @Configuration：定义配置类
• @EnableSwagger2：启用Swagger2

3. 演示代码

• 实体类：

  import io.swagger.annotations.ApiModel;
  import io.swagger.annotations.ApiModelProperty;
  
  @ApiModel(value = "用户",description = "用户的实体类")
  public class User {
      @ApiModelProperty(value = "用户id")
      private Integer id;
      @ApiModelProperty(value = "用户名")
      private String username;
      @ApiModelProperty(value = "用户地址")
      private String address;
  	//此处省略了Setter and Getter
  }
  

  @ApiModel()：用于实体类

  • value：表示对象名
  • description：描述

  @ApiModelProperty()：用于实体类字段

  • value：字段说明
  • name：重写属性名字
  • dataType：重写属性类型
  • required：是否必填
  • example：举例说明
  • hidden：隐藏

  然后打开 http://localhost:8080/swagger-ui.html#/，地址根据自己的实际运行环境决定。

  

  可以看到相关的Models的信息

• UserController类：

  import io.swagger.annotations.Api;
  import io.swagger.annotations.ApiImplicitParam;
  import io.swagger.annotations.ApiImplicitParams;
  import io.swagger.annotations.ApiOperation;
  import org.springframework.web.bind.annotation.*;
  
  @RestController
  @Api(tags = "用户管理接口")
  @RequestMapping("/user")
  public class UserController {
  
      @PostMapping("/addUser")
      @ApiOperation("添加用户")
      @ApiImplicitParams({
              @ApiImplicitParam(name = "username", value = "用户名", defaultValue = "轻舟",required = true),
              @ApiImplicitParam(name = "address", value = "用户地址", defaultValue = "南宁", required = true)
      }
      )
      public String addUser(@RequestParam(required = true) String username, @RequestParam(required = true) String address) {
          return "addUser success!";
      }
  
      @GetMapping("/{id}")
      @ApiOperation("根据id查询用户")
      @ApiImplicitParam(name = "id", value = "用户id", defaultValue = "1", required = true)
      public User getUserById(@PathVariable Integer id) {
          User user = new User();
          user.setId(1);
          user.setUsername("轻舟");
          user.setAddress("杭州");
          return user;
      }
  
      @PutMapping("/{id}")
      @ApiOperation("根据id更新用户")
      @ApiImplicitParam(name = "id", value = "用户id", defaultValue = "2", required = true)
      public Integer updateUserById(@PathVariable Integer id) {
          return 1;
      }
  }
  

  @Api()：用于类，标识此类为Swagger的资源

  • tags：分组说明标签

  @ApiOperation()：用于方法

  • value：方法的描述
  • notes：提示内容

  @ApiImplicitParam()： 用于方法

  • name：方法的参数名
  • value：参数的说明
  • dataType：数据类型
  • paramType：参数类型
  • defaultValue：参数默认值
  • required：参数是否为必须
  • example：举例说明

  @ApiIgnore()用于类或者方法上，可以不被Swagger显示在页面上

  此时我们到Swagger页面上看，有以下的结果

  

以上就是对Swagger2的简单整合了，作为本人的学习笔记，仅供参考。

如有错误，还望指正。