Swagger环境搭建及使用

Swagger环境搭建及使用

1、环境搭建

第一步：创建SpringBoot项目并引入依赖

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

第二步：编写Controller类

@RestController  //Bean中的注解
public class controllerTest {

    //Get请求
    @GetMapping("fzkGet")
    public String fzkGet(){
        return "fzkGet";
    }

    //Post请求
    @PostMapping("fzkPost")
    public String fzkPost(){
        return "fzkPost";
    }

    //Put请求
    @PutMapping("fzkPut")
    public String fzkPut(){
        return "fzkPut";
    }

    //Delete请求
    @DeleteMapping("fzkDelete/{id}")
    public String fzkDelete(@PathVariable String id){
        return "fzkDelete";
    }
}

第三步：编写Swagger配置类并加入 @EnableSwagger2 注解

@Configuration  //配置类
@EnableSwagger2  //swagger注解
public class SwaggerConfig {
}

第四步：在主配置文件中添加注解扫描

Controller类 和 Swagger类 都在 com.itfzk 包下（com.itfzk包是自己定义的包）

@SpringBootApplication
@ComponentScan(basePackages = {"com.itfzk"})  //开启注解扫描
public class Test100Application {
    public static void main(String[] args) {
        SpringApplication.run(Test100Application.class, args);
    }

}

第五步：访问测试

地址： http://localhost:8080/swagger-ui.html (localhost:8080是自己的ip地址和端口号，swagger-ui.html是显示的页面)

效果图

2、使用

配置Swagger

1、Swagger实例Bean是Docket，通过配置Docket实例来配置Swaggger
2、通过apiInfo()属性配置文档信息

@Configuration  //配置类
@EnableSwagger2  //swagger注解
public class SwaggerConfig {

    @Bean  //配置docket以配置Swagger具体参数
    public Docket webApiConfig(){
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("fzk")  //分组信息
                .apiInfo(webApiInfo());
    }

    //配置文档信息
    private ApiInfo webApiInfo(){
        //联系人信息
        Contact contact = new Contact("fzk", "https://blog.csdn.net/qq_44002865", "1820713352@qq.com");
        return new ApiInfo(
                "Swagger测试",  //标题
                "演示如何配置使用Swagger",  //描述
                "v1.0",  //版本
                "urn:tos",  //服务条件
                contact,  //联系人信息
                "Apache 2.0",  //许可
                "http://www.apache.org/licenses/LICENSE-2.0",  //许可链接
                new ArrayList<>());  //扩展
    }
}

测试效果

配置扫描接口

构建Docket时通过 select() 方法配置来扫描接口

apis()

• 使用方法

  • .select().apis(RequestHandlerSelectors.[需要扫描的配置]).build();
  • 需要扫描的配置:
    • basePackage(final String basePackage) ：根据包路径扫描接口
      • .select().apis(RequestHandlerSelectors.basePackage(“com.itfzk.controller”)).build();
        • 扫描 com.itfzk.controller 包
    • any() ：扫描所有，项目中的所有接口都会被扫描到
      • .select().apis(RequestHandlerSelectors.any()).build();
        • 扫描所有
    • none() ：不扫描接口
      • .select().apis(RequestHandlerSelectors.none()).build();
        • 不扫描
    • withMethodAnnotation(final Class<? extends Annotation> annotation) ：通过方法上的注解扫描
      • .select().apis(RequestHandlerSelectors.withMethodAnnotation(GetMapping.class)).build();
        • 只扫描get请求
    • withClassAnnotation(final Class<? extends Annotation> annotation) ：通过类上的注解扫描
      • .select().apis(RequestHandlerSelectors.withClassAnnotation(Controller.class)).build();
        • 只扫描有Controller注解的类中的接口

• 举例

  @Bean  //配置docket以配置Swagger具体参数
  public Docket webApiConfig(){
      return new Docket(DocumentationType.SWAGGER_2)
          .apiInfo(webApiInfo())
          .select()  // 通过.select()方法，配置扫描接口,RequestHandlerSelectors配置扫描接口
          .apis(RequestHandlerSelectors.basePackage("com.itfzk.test100.controller")).build();
  }
  

paths()

• 使用方法

  • .select().paths(PathSelectors.[需要扫描的配置]).build();
  • 需要扫描的配置:
    • any() ：任何请求都扫描
    • none() ：任何请求都不扫描
    • regex(final String pathRegex) ：通过正则表达式控制
    • ant(final String antPattern) ：通过ant()控制

• 举例

  @Bean  //配置docket以配置Swagger具体参数
  public Docket webApiConfig(){
      return new Docket(DocumentationType.SWAGGER_2)
          .apiInfo(webApiInfo())
          .select().paths(PathSelectors.ant("/fzk/**")).build();
  }
  

配置Swagger开关

通过 enable() 方法配置是否启用swagger，如果是false，swagger将不能在浏览器中访问了

开发和测试的时候开启，项目运行时就不启动

• 测试不启用 Swagger

  @Bean  //配置docket以配置Swagger具体参数
  public Docket webApiConfig(){
      return new Docket(DocumentationType.SWAGGER_2)
          .apiInfo(webApiInfo())
          .enable(false);  //是否启用swagger，不启用
  }
  

• 测试结果
  

配置API分组

如果没有配置分组，默认是default

通过 groupName() 方法即可配置分组

@Configuration  //配置类
@EnableSwagger2  //swagger注解
public class SwaggerConfig {
    
    @Bean  //配置docket以配置Swagger具体参数
    public Docket webApiConfig(){
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("fzk")  //配置分组 
                .apiInfo(webApiInfo());
    }
}

配置多个分组只需要配置多个docket

@Configuration  //配置类
@EnableSwagger2  //swagger注解
public class SwaggerConfig {
    
    @Bean  //配置docket以配置Swagger具体参数
    public Docket webApiConfig(){
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("fzk")
                .apiInfo(webApiInfo());
    }
    

    @Bean  //配置docket以配置Swagger具体参数
    public Docket webApiConfig1(){
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("fzk1")
                .apiInfo(webApiInfo1());
    }


    @Bean  //配置docket以配置Swagger具体参数
    public Docket webApiConfig2(){
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("fzk2")
                .apiInfo(webApiInfo2());
    }
}

常用注解

@Api()

• 用于 Controller 类上；表示标识这个类是swagger的资源

  • tags ：表示说明
  • value ：也是说明，可以使用tags替代

  @RestController
  @Api(tags = "测试Swagger")
  public class controllerTest {
  }
  

@ApiOperation()

• 用于Controller方法；表示一个http请求的操作

  • value用于方法描述
  • notes用于提示内容
  • tags可以重新分组（视情况而用）

  @RestController
  @Api(tags = "测试Swagger")
  public class controllerTest {
  
      @ApiOperation("查询Swagger")
      @GetMapping("/find")
      public String find() {
          return "Swagger";
      }
  }
  

@ApiParam()

• 用于方法，参数，字段说明；表示对参数的添加元数据（说明或是否必填等）

  • name ：参数名
  • value ：参数说明
  • required ：是否必填

  @RestController
  @Api(tags = "测试Swagger")
  public class controllerTest {
  
      @ApiOperation("查询Swagger")
      @PostMapping("/findById")
      public String find(@ApiParam(name = "id", value = "用户id", required = true) String id) {
          return "Swagger";
      }
  }
  

@ApiModel() & @ApiModelProperty()

• @ApiModel()

  • 用于类 ；表示对类进行说明，用于参数用实体类接收
    • value–表示对象名
    • description–描述
    • 都可省略

• @ApiModelProperty()

  • 用于方法，字段； 表示对model属性的说明或者数据操作更改
    • value–字段说明
    • name–重写属性名字
    • dataType–重写属性类型
    • required–是否必填
    • example–举例说明
    • hidden–隐藏

  @Data
  @ApiModel(value = "User对象", description = "用户")
  public class User {
      @ApiModelProperty(value = "用户名")
      private String userName;
  
      @ApiModelProperty(value = "密码")
      private String password;
  }