Swagger学习

Swagger

狂神swagger

Swagger简介

前后端分离

前端 -> 前端控制层、视图层

后端 -> 后端控制层、服务层、数据访问层

前后端通过API进行交互

前后端相对独立且松耦合

产生的问题

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

解决方案

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

Swagger

号称世界上最流行的API框架

Restful Api 文档在线自动生成器 => API 文档 与API 定义同步更新

直接运行，在线测试API

支持多种语言 （如：Java，PHP等）

官网：https://swagger.io/

SpringBoot集成Swagger

SpringBoot集成Swagger => springfox，两个jar包

Springfox-swagger2

swagger-springmvc

使用Swagger

要求：jdk 1.8 + 否则swagger2无法运行

步骤：

1、新建一个SpringBoot-web项目

2、添加Maven依赖

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

配置Swagger

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

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

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

//配置文档信息
private ApiInfo apiInfo() {
   Contact contact = new Contact("联系人名字", "http://xxx.xxx.com/联系人访问链接", "联系人邮箱");
   return new ApiInfo(
           "Swagger学习", // 标题
           "学习演示如何配置Swagger", // 描述
           "v1.0", // 版本
           "http://terms.service.url/组织链接", // 组织链接
           contact, // 联系人信息
           "Apach 2.0 许可", // 许可
           "许可链接", // 许可连接
           new ArrayList<>()// 扩展
  );
}

3、Docket 实例关联上 apiInfo()

@Bean
public Docket docket() {
   return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
}

配置扫描接口

@Bean
public Docket docket() {
	return new Docket(DocumentationType.SWAGGER_12)
                .apiInfo(apiInfo())
                //配置api文档的分组，如何配置多个组，有多个docket
                .groupName("老骚")
                //enable是否能启动swagger，如果为false，则swagger不能再浏览器中访问
                .enable(flag)
                .select()
                //RequestHandlerSelectors，配置要扫描的接口方式
                //basePackage：指定要扫描的包
                //any():扫描全部
                //none():不扫描
                //withClassAnnotation:扫描类上的注解，参数是一个注解的反射对象
                //withMethodAnnotation:扫描方法上的注解
//                .apis(RequestHandlerSelectors.basePackage("com.sao.swagger.controller"))
//                .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
//                .apis(RequestHandlerSelectors.withMethodAnnotation(RequestMapping.class))
                .apis(RequestHandlerSelectors.basePackage("com.sao.swagger.controller"))
                //paths:过滤什么路径
                //.paths(PathSelectors.ant("/sao/**"))
                .build();
 }

配置多个分组，配置多个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");
}

实体配置

1、新建一个实体类

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

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

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

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

也可以给请求的接口配置一些注释

@ApiOperation("狂神的接口")
@PostMapping("/kuang")
@ResponseBody
public String kuang(@ApiParam("这个名字会被返回")String username){
   return username;
}

其他皮肤

!-- 引入swagger-bootstrap-ui包 /doc.html-->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.9.1</version>
        </dependency>
        <!-- 引入swagger-ui-layer包 /docs.html-->
        <dependency>
            <groupId>com.github.caspar-chen</groupId>
            <artifactId>swagger-ui-layer</artifactId>
            <version>1.1.3</version>
        </dependency>
        <!-- 引入swagger-ui-layer包 /document.html-->
        <dependency>
            <groupId>com.zyplayer</groupId>
            <artifactId>swagger-mg-ui</artifactId>
            <version>1.0.6</version>
        </dependency>