这是我参与8月更文挑战的第13天，活动详情查看：8月更文挑战

Swagger

背景

大后端：前端只管理静态页面htmk，css，后端使用模板引擎

前后端分离：

• 后端：后端控制器，服务层，数据访问层

• 前端：前端控制层，视图层

  • 前端可以通过伪造后端数据，不依靠后端也能跑起来（前端工程化）

• 前后端如何交互：通过接口，传递json数据

• 前后端相对独立，松耦合，可以部署在不同的服务器上

产生的问题：

• 前后端沟通困难，改变业务麻烦

解决问题

• 指定完善的schema，实时更新API，降低集成风险
• 前端测试后端接口：postman
• 后端提供接口，需要实时更新最新更改

优点

更快捷更方便进行接口API的开发

• 最流行的API框架
• 是Resultful风格的API ，文档自动生成：API文档与API定义同步更新
• 可以直接运行，在线测试API接口
• 支持多种语言

集合成springboot

入门

1.创建项目，选择web，然后导包

<!-- 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.配置Swagger

SwaggerConfig:什么都没写就是默认设置

@Configuration
@EnableSwagger2
public class SwaggerConfig {
​
       
}

3.编写controller和测试

@RestController
public class Controller {
​
   @RequestMapping("/hi")
   public String show(){
       return "hi";
  }
}

访问网页

配置Swagger

Swagger的bean实例Docket

• 过滤器 paths（PathSelectors.xxx）
• 接口扫描 apis(RequestHandlerSelectors.XXX）
• 开启关闭 enable（）
• 分组 groupName（）
• 文档信息 apiInfo（）

@Configuration
@EnableSwagger2
public class SwaggerConfig {
​
   @Bean
   public Docket docket1(){
       return new Docket(DocumentationType.SWAGGER_2).groupName("Y1Y");
  }
   @Bean
   public Docket docket2(){
       return new Docket(DocumentationType.SWAGGER_2).groupName("Y2Y");
  }
​
   @Bean
   public Docket docket(@Qualifier("apiInfo") ApiInfo apiInfo,Environment environment){
       
       Profiles dev = Profiles.of("dev");
       boolean isdev = environment.acceptsProfiles(dev);
​
       return new Docket(DocumentationType.SWAGGER_2)
              .apiInfo(apiInfo)
              .enable(isdev)
              .groupName("YZY")
              .select()
            .apis(RequestHandlerSelectors.basePackage("com.example.swagger.controller"))
              .paths(PathSelectors.any())
              .build();
  }
​
  
​
   @Bean
   public ApiInfo apiInfo(){
​
       Contact contact = new Contact("YZY","http://localhost:8080/swagger-ui.html#/","1061603811@qq.com");
       return new ApiInfo("YZY的API文档",
               "文档描述",
               "1.1",
               "http://localhost:8080/swagger-ui.html#/", contact,
               "Apache 2.0",
               "http://www.apache.org/licenses/LICENSE-2.0",
               new ArrayList());
  }
}

实体类

先要在文档显示实体类，需要在controller返回实体类，

1.创建一个新的controller编写返回实体类的请求

@RestController
@Api(tags = "实体类")
@RequestMapping("/entity")
public class BusEntityController {
​
   @ApiOperation("车辆")
   @PostMapping("/BusCar")
   public BusCar busCar(){
       return new BusCar();
  }
​
   @ApiOperation("司机")
   @PostMapping("/BusDriver")
   public BusDriver busDriver(){
       return new BusDriver();
  }
​
  ......
}
​

2.实体类添加注释

@ApiModel("车站")为实体类添加注释

@@ApiModelProperty("发班总数",example="")为字段添加注释，注意，如果字段为Integer类型，需要添加example条件指定默认值，这边的example="0"只会在Swagger测试中默认，对正常的业务没有影响

@ApiModel("路线")
public class BusRoute implements Serializable {
   private String id;
   private String busStationId;
   @ApiModelProperty("起点")
   private String start;
   @ApiModelProperty(value = "每日班次",example = "0")
   private Integer time;

返回的实体类就会显示在models上，controller中部没有回的实体类不会出现在models上

注释

@Api(tags="司机列表")为controller类加注释

@ApiOperation("查询")为controller的方法加注释

@RestController
@Api(value="车辆controller",tags={"车辆列表"})
@RequestMapping("/car")
public class BusCarController {
​
   @ApiOperation("查询全部")
   @PostMapping("/selectAll")
   public Map<String,Object> selectAll(){
      
  }

测试

总结作用

1.接口文档的设置（配置文件）

2.在线测试

在正式发布需要关闭为了安全和效率