Swagger接口工具

1、简介

在前后端分离开发的过程中，前端和后端需要进行api对接进行交互，就需要一个api规范文档，但api文档不能根据代码的变化发生实时动态的改变，这样后端修改了接口，前端也不能及时获取最新的接口，导致调用出错，需要手动维护api文档，加大了开发的工作量和困难，而swagger的出现就是为了解决这一系列的问题。

Swagger是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。Swagger是一个规范和完整的框架,用于生成、描述、调用和可视化RESTful风格的Web服务。目标是使客户端和文件系统作为服务器以同样的速度来更新文件的方法,参数和模型紧密集成到服务器。简单来说，swagger是一款可以根据resutful风格生成的生成的接口开发文档，并且支持做测试的一款中间软件。

2、快速上手

2.1、导入依赖

创建一个SpringBoot项目，导入两个依赖。

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

2.2、编写配置类

新建config包，创建SwaggerConfig配置类，打上@Configuration代表这是配置类，@EnableSwagger2打开Swagger的功能，什么都不写，启动，先访问http://localhost:8080/swagger-ui.html

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    
}

配置Swawgger信息

配置Swagger的Docket的bean实例，用于将Swagger默认的配置内容换成你自己的api信息，作者信息，文档说明，版本号，服务条款地址，全部在apiInfo方法中，作者信息需要new一个Contact对象，将个人信息塞进去。

@Configuration
@EnableSwagger2
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("zm", "https://www.cnblogs.com/zm-111/", "3339332352@qq.com");
        return new ApiInfo(
                "zmのSwaggerAPI文档",
                "菜鸡来了~~~",
                "2.0",
                "https://www.cnblogs.com/zm-111/",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList());
    }
}

重启再次访问

2.3、配置扫描接口及开关

先写一个controller，mySwagger

@Controller
public class MyController {
    @ResponseBody
    @RequestMapping("/mySwaggerController")
    public String mySwagger(){
        return "hello";
    }
}

RequestHandlerSelectors是配置扫描包的方式的，它有5种方式

  • basePackage，基于包扫描；一般就用这个

  • any，扫描全部

  • none，什么都不扫描

  • witchClassAnnotatopn，基于类的注解扫描

  • witchMethodAnnotatopn，基于方法的注解扫描

基于包扫描，这时的controller就是自己刚才定义的了。

paths扫描指定的请求路径，ant("/aaa/**"))在原来的包里扫描到的所有请求路径中，我只要/aaa/下面的，由于controller中确实没有这个请求，所以未定义。

.paths(PathSelectors.ant("/aaa/**"))

swagger的开关是否启动，enabled=true默认的，改成false就关闭了

关闭后的样子

@Bean
public Docket docket(){
​
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .enable(false)
            .select()
            //RequestHandlerSelectors配置要扫描接口的方式
            //basePackage基于包扫描
            //withClassAnnotation,扫描类上的注解,withClassAnnotation(Controller.class)
            //withMethodAnnotation，扫描方法上的注解withMethodAnnotation(RequestMapping.class))
            .apis(RequestHandlerSelectors.basePackage("com.zm.controller"))
            //paths扫描指定的请求路径，ant("/aaa/**"))在原来的包里扫描到的所有请求路径中，我只要/aaa/下面的
            .paths(PathSelectors.ant("/aaa/**"))
            .build();
}

一个问题：如果，我只希望我的Swagger在生产环境中使用，在发布的时候不使用

  • 先判断是不是生产环境 设置flag=false

  • 注入enabled=flag

多配置文件，dev开发环境，uat测试环境，prod生产环境，开发->测试->上线

新建两个配置文件

application-dev.properties

server.port=8081

application-prod.properties

server.port=8082

在源配置文件中选择启用哪一个环境

spring.profiles.active=dev

在配置类中设置Swagger要显示的环境，也可以直接打上注解@Profiles("dev")

@Bean
public Docket docket(Environment environment){
    //设置要显示的swagger环境
    //1 获取要显示的配置文件
    Profiles profiles = Profiles.of("dev","test");
    //2 通过environment.acceptsProfiles判断是否处在自己设定的环境中，返回的布尔值丢给enabled
    boolean flag = environment.acceptsProfiles(profiles);
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .enable(flag)
            .select()
            //RequestHandlerSelectors配置要扫描接口的方式
            //basePackage基于包扫描
            //withClassAnnotation,扫描类上的注解,withClassAnnotation(Controller.class)
            //withMethodAnnotation，扫描方法上的注解withMethodAnnotation(RequestMapping.class))
            .apis(RequestHandlerSelectors.basePackage("com.zm.controller"))
            //paths扫描指定的请求路径，ant("/aaa/**"))在原来的包里扫描到的所有请求路径中，我只要/aaa/下面的
            .paths(PathSelectors.ant("/aaa/**"))
            .build();
}

启动测试，现在要访问文档就得是8081的端口了，8080就是未找到

8081可以

2.4、配置分组和接口注释

groupName()设置分组名字

.groupName("zm")

如何设置多个分组，就创建多个docket实例就行了。

   //创建多个分组，就创建多个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组");}

实体类---model，只要请求中返回值是一个实体，他就会自动被扫描到，使用@ApiModel("用户实体类")和@ApiModelProperty("用户名")分别给实体类和其属性添加注解

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

controller中添加请求也就是接口/user

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

@ApiOperation给接口注释，@ApiParam是接口参数的注释

//@ApiOperation给接口注释，@ApiParam是接口参数的注释
@ApiOperation("哈喽控制类")
@GetMapping("/hello")
public String helloSwagger(@ApiParam("用户名接口参数") String name){
    return "hello"+name;
}

测试功能，有参数就传递参数再测试，执行后它会及时反馈将结果直接展示出来。

总结

  • 我们可以通过Swagger给一些比较难理解的属性和接口添加注解信息，让别人能容易理解；

  • 接口文档可实时更新；

  • 可以在线测试；

  • 在正式发布的时候，关闭Swagger，出于安全考虑且省内存。