目标:
前后端分离
VUE+springBoot
产生的问题
前后端集成,前端或者后端无法做到“及时协商,尽早解决”,最终导致问题集中爆发
解决方案
首先定义计划的提纲,并实时跟踪最新的API,降低集成风险
Swagger
新建一个springboot-web项目
下载maven依赖https://mvnrepository.com/search?q=springfox
<!-- 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>
高版本是没有第5部的测试页面
3.0.0版本的要先在启动类中加上注解@EnableOpenApi先在导入<groupId>io.springfox</groupId><artifactId>springfox-boot-starter</artifactId>
编写Controller,测试运行成功
配置Swagger=》在包Config下
package com.hxl.config; import org.springframework.context.annotation.Configuration; import springfox.documentation.swagger2.annotations.EnableSwagger2; @Configuration @EnableSwagger2 //开启swagger2 public class SwaggerConfig { }
测试运行:http://localhost:8080/swagger-ui.html
Swagger实例Bean是Docket,所以通过配置Docket实例来配置Swaggger。
//配置了Swagger的Docket实例 @Bean public Docket docket(){ return new Docket(DocumentationType.SWAGGER_2); }
再通过ApiInfo()属性配置文档信息
private ApiInfo apiInfo(){ //作者信息 Contact contact = new Contact("王木木","https://blog.csdn.net/qq_43585922?spm=1000.2115.3001.5343","11@qq.com"); return new ApiInfo( "Swagger笔记", //标题 "冲冲冲", //描述 "v1.0。0", //版本 "https://blog.csdn.net/qq_43585922?spm=1000.2115.3001.5343", //组织链接 contact, //联系人信息 "Apach 2.0 许可", //许可 "许可链接", //许可连接 new ArrayList<>()//扩展 ); }
Docket关联上ApiInfo
@Bean public Docket docket(){ return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()); }
启动项目,访问http://localhost:8080/swagger-ui.html
构建Docket时通过select()
方法配置怎么扫描接口。select()
和build()
是一套的
//配置了Swagger的Docket实例 @Bean public Docket docket(){ return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() /* RequestHandlerSelectors:要扫描接口的方式 basePackage:指定要扫描的包 any():扫描全部 none():不扫描 withClassAnnotation:扫描类上的注解,参数是一个注解的反射对象 withMethodAnnotation:扫描方法上的注解 path():过滤什么路径 */ .apis(RequestHandlerSelectors.basePackage("com.hxl.controller")) //.paths(PathSelectors.ant("/hxl/**")) .build(); }
我们看之前的运行结构可以看到有base-error-controller
和hello-controller
,一旦使用了上述配置后,运行结果只有hello-controller
通过enable()方法配置是否启用swagger
@Bean public Docket docket(){ return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) //enable是否启动Swagger,默认为true,如果该位false则不能在浏览器中访问 .enable(false) .select() /* RequestHandlerSelectors:要扫描接口的方式 basePackage:指定要扫描的包 any():扫描全部 none():不扫描 withClassAnnotation:扫描类上的注解,参数是一个注解的反射对象 withMethodAnnotation:扫描方法上的注解 path():过滤什么路径 */ .apis(RequestHandlerSelectors.basePackage("com.hxl.controller")) //.paths(PathSelectors.ant("/hxl/**")) .build(); }
Swagger在生产环境中使用,在发布的时候不使用
当我们有多个生产环境时。比如说application-dev.yaml
和application-pro.yaml
。动态设置当前项目处于dev时显示swagger,Pro是不显示
#哪个环境生效
spring.profiles.active=dev
设置我们的dev走8081,默认走8080,pro走8082
然后修改我们的配置
@Bean public Docket docket(Environment environment){ //设置显示的Swagger环境 Profiles profiles = Profiles.of("dev", "test"); //通过 判断是否处在自己设定的环境中 boolean flag = environment.acceptsProfiles(profiles); return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) //这里变成了flag .enable(flag) .select() .apis(RequestHandlerSelectors.basePackage("com.hxl.controller")) .build(); }
此时我们就发现,如果我们走默认的8080是没有Swagger的,走8081才有
@Bean public Docket docket(Environment environment){ return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .groupName("王木木"); //其余配置省略 }
启动项目就发现我们的组别有了
如果有多个分组怎么办?只需要配置多个docket
即可
//其他的环境需要自己填 @Bean public Docket docket1(){ return new Docket(DocumentationType.SWAGGER_2).groupName("天"); } @Bean public Docket docket2(){ return new Docket(DocumentationType.SWAGGER_2).groupName("狼"); }
创建一个实体类
package com.hxl.pojo; public class User { public String username; public String password; }
只要这个实体在请求接口的返回值上,就可以映射到实体项中
//只要我们的接口中,返回值存在实体类,他就会扫描到Swagger中 @PostMapping("/user") public User user(){ return new User(); }
测试
此时发现我们的Model中有了User。如果有中文的注释,只需要在加两个注解
package com.hxl.pojo; import io.swagger.annotations.ApiModel; import io.swagger.annotations.ApiModelProperty; //@Api("注释") @ApiModel("用户实体类") public class User { @ApiModelProperty("姓名") public String username; @ApiModelProperty("密码") public String password; }
测试
Swagger的所有注解定义在io.swagger.annotations包下
Swagger注解 | 简单说明 |
---|---|
@Api(tags = “xxx模块说明”) | 作用在模块类上 |
@ApiOperation(“xxx接口说明”) | 作用在接口方法上 |
@ApiModel(“xxxPOJO说明”) | 作用在模型类上:如VO、BO |
@ApiModelProperty(value = “xxx属性说明”,hidden = true) | 作用在类方法和属性上,hidden设置为true可以隐藏该属性 |
@ApiParam(“xxx参数说明”) | 作用在参数、方法和字段上 |
注解在类上的可以看一下上面的,接下来看注解在接口方法上,以及参数上
@ApiOperation("王木木的接口") @PostMapping("/hxl") public String hxl(@ApiParam("用户名")String username){ return username; }
在这里还可以进行测试