Swagger工具

创建项目

1.新建一个SpringBoot = >web项目

2.导入相关依赖

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>3.0.0</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>3.0.0</version>
</dependency>

注意：

如果使用的是swagger 3.0版本，需要加一个依赖，访问：http://localhost:8080/swagger-ui/index.html , 就可以对swagger-ui.html访问。

     <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>

3.编写一个Hello工程

4.配置Swagger -->Config

@Configuration
@EnableSwagger2   //开启swagger2
public class SwaggerConfig {

}

5.测试运行
访问：http://localhost:8080/swagger-ui.html

配置Swagger信息

1.配置基本信息

package com.txb.swagger.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;


@Configuration
@EnableSwagger2   //开启swagger2
public class SwaggerConfig {

    //配置了Swagger的Docket的Bean实例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
    }

    //配置Swagger信息=apiInfo
    private ApiInfo apiInfo(){

        //作者信息
        Contact contact = new Contact("田秀彪", "https://blog.csdn.net/txb116424?spm=1001.2101.3001.5343", "1164241117@qq.com");

        return new ApiInfo(
                "我的API文档",
                "hello world",
                "v1.0",
                "https://blog.csdn.net/txb116424?spm=1001.2101.3001.5343",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }
}

配置完成重启项目，页面文字就会成为自己配置的

2.Swagger配置扫描接口
Docket.select()

  @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //RequestHandlerSelectors,配置要扫描接口的方式
                //basePackage:指定要扫描的包
                //any():扫描全部
                //none:不扫描
                //withClassAnnotation:扫描类上的注解，参数是一个注解的反射对象
                //withMethodAnnotation:扫描方法上的注解
                .apis(RequestHandlerSelectors.basePackage("com.txb.swagger.controller"))
                //paths().过滤什么路径
                .paths(PathSelectors.ant("/txb/**"))
                .build();
    }

3.配置是否启动Swagger

//配置了Swagger的Docket的Bean实例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(false)  //enable是否启动Swagger，如果为false，则Swagger不能在浏览器中访问
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.txb.swagger.controller"))
                .build();
    }

4.只希望我的Swagger在生产环境中使用，在发布的时候不使用？

• 判断是不是生产环境 flag = false
• 注入enable （flag）

//配置了Swagger的Docket的Bean实例
    @Bean
    public Docket docket(Environment environment){
        //设置要显示的Swagger环境
        Profiles profiles = Profiles.of("dev","test");

        //通过environment.acceptsProfiles判断是否处在自己设定的环境当中
        boolean flag = environment.acceptsProfiles(profiles);
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(false)  //enable是否启动Swagger，如果为false，则Swagger不能在浏览器中访问
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.txb.swagger.controller"))
            
                .build();
    }

配置API文档的分组

.groupName(“A”)

如何配置多个分组，多个Docket实例即可

@Bean
    public Docket docket1(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("A");
    }

    @Bean
    public Docket docket2(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("B");
    }

    @Bean
    public Docket docket3(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("C");
    }

实体类配置

1.新建实体类（属性必须用public修饰，否则扫描不到）

@ApiModel("用户实体")
public class User {
   @ApiModelProperty("用户名")
   public String username;
   @ApiModelProperty("密码")
   public String password;
}

2.将实体绑定在请求接口的返回值上，才能映射到实体中。

@RequestMapping("/user")
public User user(){
   return new User();
}

3.启动项目，查看实体model

注：

@ApiModel和@ApiModelProperty这两个注解只是为实体添加注释的。
@ApiModel为类添加注释
@ApiModelProperty为类属性添加注释

还可以用Swagger来进行测试

1.写一个方法来返回user对象。

 @ApiOperation("Post测试类")
    @PostMapping(value = "/postt")
    public User postt(@ApiParam("用户名") User user){
        int i = 5/0;
        return user;
    }

2.在controller下找到对应方法。

3.点击try it out 输入测试的参数，excute（执行）。


4.可以看到执行后的状态码，查看是否成功。

相较于传统的Postman或Curl方式测试接口，使用swagger简直就是傻瓜式操作，不需要额外说明文档(写得好本身就是文档)而且更不容易出错，只需要录入数据然后点击Execute，如果再配合自动化框架，可以说基本就不需要人为操作了。

Swagger是个优秀的工具，现在国内已经有很多的中小型互联网公司都在使用它，相较于传统的要先出Word接口文档再测试的方式，显然这样也更符合现在的快速迭代开发行情。当然了，提醒下大家在正式环境要记得关闭Swagger，一来出于安全考虑二来也可以节省运行时内存。

参考视频

https://www.bilibili.com/medialist/play/ml1279355417/BV1Y441197Lw