东方证券程序化交易接口-swagger详细讲解_ 股票程序化软件自动交易接口

学习目标：了解Swagger的概念及作用掌握在项目中集成Swagger自动生成API文档

前后端分离

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

产生的问题

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

解决方案

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

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

使用Swagger要求：jdk8+否则swagger2无法运行步骤：新建一个SpringBoot-web项目添加Maven依赖

编写HelloController，测试确保运行成功！要使用Swagger，我们需要编写一个配置类-SwaggerConfig来配置Swagger

@Configuration //配置类
@EnableSwagger2// 开启Swagger2的自动配置
public class SwaggerConfig {  
}

配置Swagger

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

@Bean
public Docket docket() {
   return new Docket(DocumentationType.SWAGGER_2)
      .apiInfo(apiInfo())
      .enable(true) //配置是否启用Swagger，如果是false，在浏览器将无法访问
      .select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
.apis(RequestHandlerSelectors.basePackage("com.cjdx.swagger.controller"))
       // 配置如何通过path过滤,即这里只扫描请求以/hello开头的接口,可不写
      .paths(PathSelectors.ant("/hello/**"))
      .build();
}

可以通过apiInfo属性配置文档信息

any() // 扫描所有，项目中的所有接口都会被扫描到
none() // 不扫描接口
// 通过方法上的注解扫描，如withMethodAnnotation(GetMapping.class)只扫描get请求
withMethodAnnotation(final Class<? extends Annotation> annotation)
// 通过类上的注解扫描，如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接口
withClassAnnotation(final Class<? extends Annotation> annotation)
basePackage(final String basePackage) // 根据包路径扫描接口

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

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

配置API分组

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

@Bean
public Docket docket(Environment environment) {
   return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
      .groupName("hello") // 配置分组
       // 省略配置....
}

重启项目查看分组如何配置多个分组？配置多个分组只需要配置多个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");
}

重启项目查看即可

实体配置

新建一个实体类

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

只要这个实体在请求接口的返回值上，都能映射到实体项中：

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

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

常用注解

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

举例：类