SpringBoot集成Swagger

Swagger简介

兴起原因

由于前后端分离项目的兴起开发模式变为：

前端 -> 前端控制层、视图层
后端 -> 后端控制层、服务层、数据访问层
前后端通过API进行交互
前后端相对独立且松耦合

产生的问题：前后端集成，前端或者后端无法做到“及时协商，尽早解决”，最终导致问题集中爆发

解决方案：首先定义schema [ 计划的提纲 ]，并实时跟踪最新的API，降低集成风险

简介

Swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

Swagger 的目标是对 REST API 定义一个标准且和语言无关的接口，可以让人和计算机拥有无须访问源码、文档或网络流量监测就可以发现和理解服务的能力。当通过 Swagger 进行正确定义，用户可以理解远程服务并使用最少实现逻辑与远程服务进行交互。与为底层编程所实现的接口类似，Swagger 消除了调用服务时可能会有的猜测。

号称世界上最流行的API框架
Restful API 文档在线自动生成器 => API 文档与API 定义同步更新
直接运行，在线测试API
支持多种语言（如：Java，PHP等）
官网：https://swagger.io/

环境准备

要求使用jdk1.8+否则swagger2无法运行

1.首先创建一个SpringBoot-Web项目，添加项目依赖.

<!--swagger2-->
   <dependency>
       <groupId>io.springfox</groupId>
       <artifactId>springfox-swagger2</artifactId>
       <version>2.9.2</version>
   </dependency>
   <!--swagger-ui-->
   <dependency>
       <groupId>io.springfox</groupId>
       <artifactId>springfox-swagger-ui</artifactId>
       <version>2.9.2</version>
   </dependency>

2.编写HelloController，进行测试。

3.要使用Swagger，我们需要编写一个配置类配置Swagger。使用@EnableSwagger2开启swagger2

4.启动项目，访问测试。swagger-ui地址是在项目目录下加上swagger-ui.html——http://localhost:8080/swagger-ui.html。成功访问。页面中的HelloController就是我们配置的controller接口。

配置Swagger

1.Swagger实例Bean是Docket，所以通过配置Docket实例来配置Swaggger。

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

2.可以通过apiInfo()属性配置文档信息

//配置Swagger信息 apiInfo
private ApiInfo apiInfo(){
    Contact contact = new Contact("Kylin","https://ww.kylin.show","zhang171346168@qq.com");
    return new ApiInfo(
            "Kylin的SwaggerAPI文档",//标题
            "学习不易，努力努力~",//描述
            "v1.0",//版本
            "https://www.kylin.show",//组织链接
            contact,//联系人信息
            "Apache 2.0",//许可
            "http://www.apache.org/licenses/LINCENSE-2.0",//许可链接
            new ArrayList());
}

3.Docket 实例通过apiInfo关联上apiInfo()

return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());

4.启动项目，访问页面。查看定制的效果。

配置扫描接口

1.构建Docket时通过select()方法配置怎么扫描接口。RequestHandlerSelectors配置如何扫描接口。通过build()构建

basePackage():指定要扫描的包
any():扫描全部
none():不扫描
withClassAnnotation():扫描类上的注解参数是一个注解的反射对象
withMethodAnnotation():扫描方法上的注解

2.除此之外，我们还可以通过paths()配置接口扫描过滤

any() // 任何请求都扫描
none() // 任何请求都不扫描
regex(final String pathRegex) // 通过正则表达式控制
ant(final String antPattern) // 通过ant()控制

//配置了Swagger的Docket的bean实例
@Bean
public Docket docket(Environment environment){

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

3.重新启动项目，访问页面查看效果。

发现没有接口被扫描到。这是因为在我们指定的com.kylin.wagger.controller下的HelloController中没有/kylin/**的请求所以没有匹配到合适的接口。

4.我们可以在controller中增加一个get请求映射/test.。然后修改.paths(PathSelectors.ant("/hello/**"))

5.重启项目进行测试

正确扫描到了接口，并且扫描到了/hello请求，而过滤掉了非/hello/**的请求也就是测试中的/test。

通过select()你可以选择你要扫描的接口的方式，在此基础上又可以通过path()对请求路径进行过滤，只扫描匹配的接口中请求。可以更加灵活的定制你想要扫描到的接口

注意当你的请求映射没有指明请求方式时，Swagger会自动生成多种不同的请求方式。例如

因此我们要对其指定请求的方式

配置API分组

1.如果没有配置分组，默认是default。通过groupName()方法即可配置分组

2.如何配置多个分组？配置多个分组只需要配置多个docket即可

@Bean
public Docket docket1(){
   return new Docket(DocumentationType.SWAGGER_2).groupName("group1");
}
@Bean
public Docket docket2(){
   return new Docket(DocumentationType.SWAGGER_2).groupName("group2");
}
@Bean
public Docket docket3(){
   return new Docket(DocumentationType.SWAGGER_2).groupName("group3");
}

3.启动项目查看效果

配置Swagger开关

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

2.如何动态配置当项目处于test、dev环境时显示swagger，处于prod时不显示？首先创建两个配置文件。

docket实例中加入Environment类型参数，通过Profiles.of()设置要显示的Swagger环境。通过通过environment.acceptProfiles判断是否处在自己设定的环境中,判断结果被boolean类型flag接收。enable(flag)

在application.properties中配置激活指定的profile，我们首先来激活devspring.profiles.active=dev

正常显示。我们修改激活的profile为prodspring.profiles.active=dev

页面将不在正常显示！

实体配置

1.新建一个实体类User

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

2.只要这个实体在请求接口的返回值上（即使是泛型），都能映射到实体项中.

//只要我们的接口中，返回值存在实体类，他就会被扫描
@PostMapping("/user")
public User user(){
    return new User();
}

3.启动测试，查看效果(前文中的path()已经注释，/test已经删除)

注：并不是因为@ApiModel这个注解让实体显示在这里了，而是只要出现在接口方法的返回值上的实体都会显示在这里，而@ApiModel和@ApiModelProperty这两个注解只是为实体添加注释的。

@ApiModel为类添加注释

@ApiModelProperty为类属性添加注释

常见注解

Swagger的所有注解定义在io.swagger.annotations包下。下面列一些经常用到的，未列举出来的可以另行查阅说明：

注解	作用
@Api(tags = “xxx模块说明”)	作用在模块类上
@ApiOperation(“xxx接口说明”)	作用在接口方法上
@ApiModel(“xxxPOJO说明”)	作用在模型类上
@ApiModelProperty(value = “xxx属性说明”,hidden = true)	作用在类方法和属性上，hidden设置为true可以隐藏该属性
@ApiParam(“xxx参数说明”)	作用在参数、方法和字段上
@ApiModelProperty	作用在参数、方法和字段上，类似@ApiModelProperty