swagger 2速成
在说swagger之前，不得不提前后端分离开发的概念。现如今，最流行的开发方式是 vue + springbot 协同开发。vue作为最流行的渐进式框架，它只关心视图层（soc关注度分离原则）与第三方库做交互，有着双向绑定的特点。springboot 不用多说，它是当前最流行的后端框架！
目录
前后端分离
前后端分离的优点
容易产生的问题
解决方案
swagger的特点和概念
在springboot中集成swagger
搭建项目
配置swagger
配置扫描接口和开关
如何设置我的swagger在生产环境中使用 在发布的时候不使用
分组和接口注释
总结
前后端分离
在过去的后端时代，后端人员是主力，前端只需要管理静态页面，写html，甚至只需要使用画图工具即可完成开发，工作量少，薪资低。而后端的工作就很多了，要先把前端人员提供的html用模板引擎构建出来，如jsp等，然后才能进行接下来的操作。
而现在，前后端分离时代来了，不仅后端有分层开发，前端也有！
- 后端：后端控制层，服务层，数据访问层
- 前端：前端控制层，视图层
对于现在的前端人员，通过伪造的数据，在没有后端提供数据的前提下，也能把项目跑起来！
那么，现在用什么方式交互前后端呢？--》 api 接口 ，后端人员提供接口，前端从接口中获取数据渲染到页面上，实现前后端分离开发
前后端分离的优点
- 前后端彼此相对独立，耦合度低，前后端甚至可以部署在不同的服务器上
- 人员分工更加明确，项目开发速度快，效率高
容易产生的问题
- 前后端集成联调，前端人员和后端人员无法做到“及时协商，尽早解决”，最终导致问题集中爆发
解决方案
- 制定提纲，实时更新最新api，降低集成的风险
- 早些年，使用word制定计划，虽然提取下载文档操作不方便，但也算是解决了这个问题
- 后来，使用一些第三方工具来快速获取接口中的内容，如 postman
- 现在，swagger！
swagger的特点和概念
- swagger号称世界上最流行的api框架
- 使用restful 风格的api 文档在线自动生成工具 api 文档与 api 定义同步更新
- 直接运行，可以在线测试api接口
- 支持多种语言
官网
在springboot中集成swagger
- 在项目中使用需要引入springfox相关jar包
- 配置swagger2
- 访问swagger-ui
搭建项目
- 新建一个springboot项目 --web项目
- 去maven官网找需要用的jar包
io.springfox springfox-swagger2 2.9.2 io.springfox springfox-swagger-ui 2.9.2 - 编写一个hello world
- 配置swagger==》config 开启swagger2 enableSwagger2
@Configuration @EnableSwagger2 //开启swagger2 public class swaggerConfig { } - 访问测试 http://localhost:8080/swagger-ui.html
如果出现404无法访问的情况，修改依赖版本为2.9.2即可，博主之前用的3.0.0就出现了这个问题
配置swagger
- swagger配置类里有 bean实例docket
@Configuration
@EnableSwagger2 //开启swagger2
public class swaggerConfig {
//配置了swagger的docket的bean实例
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo());
}
//配置swagger信息 = apiInfo
private ApiInfo apiInfo(){
Contact contact = new Contact("赵敬轩","123","[email protected]");
return new ApiInfo(
"赵敬轩的接口文档",
"大隐隐于市，努力即成功",
"1.0",
"123",
contact,
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList()
);
}
}
配置扫描接口和开关
通过docket中的select()方法可以配置要扫描哪些接口 ，每一个select()方法都要对应一个build()方法，有 select() 就必须要有build()
例如 扫描GetMapping接口
//配置了swagger的docket的bean实例
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.withMethodAnnotation(GetMapping.class))
.build();
}controller
@Controller
public class helloSwagger {
@ResponseBody
@RequestMapping("hello")
public String hello(){
return "hello,swagger";
}
@ResponseBody
@GetMapping("hi")
public String hi(){
return "hi";
}
}效果
扫描的规则
- RequestHandlerSelectors配置要扫描接口的方式
- basePackage指定要扫描的包
- any()扫描全部
- none()不扫描
- withClassAnnotation 扫描类上的注解 参数是一个注解的反射对象
- withMethodAnnotation 扫描方法上的注解
修改 GetMapping 为 RequestMapping、
RequestMapping() 如果不指定请求方式，默认全部请求一遍get,post,head,put,delete..
在扫描代码段后可以接过滤器
paths 过滤哪些路径
如何设置我的swagger在生产环境中使用 在发布的时候不使用
- 判断是不是生产环境
- enable
1.新建环境文件，prod和dev
2.主properties里激活生产环境
3.配置swaggerConfig
4.测试
分组和接口注释
分组
修改组名
添加组员
/**
* 添加组员
*/
@Bean
public Docket docket1(){
return new Docket(DocumentationType.SWAGGER_2).groupName("小明");
}
@Bean
public Docket docket2(){
return new Docket(DocumentationType.SWAGGER_2).groupName("小张");
}
@Bean
public Docket docket3(){
return new Docket(DocumentationType.SWAGGER_2).groupName("小李");
}效果
接口注释
为实体类和属性添加注释
为接口方法添加注释
效果
测试
接口使用测试
报错测试
总结
swagger简单容易上手是他最大的优点，与postman对比，体积更小，集成在项目中，项目成员更容易协调沟通。swagger集文档注解，接口注释，实时测试功能于一身，是现如今最火爆的框架！
需要注意的是，在项目正式上线后，要关闭swagger文档，这样不但可以防止接口信息被暴露，而且可以加快项目运行速度。