网站猜你喜欢代码,directadmin备份网站,注册人力资源公司需要什么手续,站群系列服务器做视频网站文章目录 前言一、Swagger简介二、SpringBoot集成Swagger三、配置Swagger四、配置扫描接口五、配置Swagger开关六、配置API分组七、实体配置八、常用注解 前言
作为后端开放人员#xff0c;最烦的事就是自己写接口文档和别人没有写接口文档#xff0c;不管是前端还是后端开发… 文章目录 前言一、Swagger简介二、SpringBoot集成Swagger三、配置Swagger四、配置扫描接口五、配置Swagger开关六、配置API分组七、实体配置八、常用注解 前言
作为后端开放人员最烦的事就是自己写接口文档和别人没有写接口文档不管是前端还是后端开发多多少少都会被接口文档所折磨前端会抱怨后端没有及时更新接口文档而后端又会觉得编写接口文档太过麻烦。Swagger 可以较好的接口接口文档的交互问题以一套标准的规范定义接口以及相关的信息就能做到生成各种格式的接口文档生成多种语言和客户端和服务端的代码以及在线接口调试页面等等。只需要更新 Swagger 描述文件就能自动生成接口文档做到前端、后端联调接口文档的及时性和便利性。 一、Swagger简介
1.前后端分离 前端 - 前端控制层、视图层 后端 - 后端控制层、服务层、数据访问层 前后端通过API进行交互 前后端相对独立且松耦合
2.产生的问题
前后端集成前端或者后端无法做到“及时协商尽早解决”最终导致问题集中爆发
3.解决方案
首先定义schema [ 计划的提纲 ]并实时跟踪最新的API降低集成风险
4…Swagger 号称世界上最流行的API框架 Restful Api 文档在线自动生成器 API 文档 与API 定义同步更新 直接运行在线测试API 支持多种语言 如JavaPHP等 官网https://swagger.io/
二、SpringBoot集成Swagger
1…SpringBoot集成Swagger springfox两个jar包 Springfox-swagger2 swagger-springmvc 2.Swagger的使用
要求jdk 1.8 否则swagger2无法运行 步骤
1、新建一个SpringBoot-web项目
2、添加Maven依赖
!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 --
dependencygroupIdio.springfox/groupIdartifactIdspringfox-swagger2/artifactIdversion2.9.2/version
/dependency
!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui --
dependencygroupIdio.springfox/groupIdartifactIdspringfox-swagger-ui/artifactIdversion2.9.2/version
/dependency3、编写HelloController测试确保运行成功
4、要使用Swagger我们需要编写一个配置类-SwaggerConfig来配置 Swagger
Configuration //配置类
EnableSwagger2// 开启Swagger2的自动配置
public class SwaggerConfig {
}5、访问测试 http://localhost:8080/swagger-ui.html 可以看到swagger的界面
三、配置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());
}4.重启项目访问测试 http://localhost:8080/swagger-ui.html 看下效果
四、配置扫描接口
1.构建Docket时通过select()方法配置怎么扫描接口。
Bean
public Docket docket() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()// 通过.select()方法去配置扫描接口,RequestHandlerSelectors配置如何扫描接口.apis(RequestHandlerSelectors.basePackage(com.kuang.swagger.controller)).build();
}2.重启项目测试由于我们配置根据包的路径扫描接口所以我们只能看到一个类
3、除了通过包路径配置扫描接口外还可以通过配置其他方式扫描接口这里注释一下所有的配置方式
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) // 根据包路径扫描接口4、除此之外我们还可以配置接口扫描过滤
Bean
public Docket docket() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()// 通过.select()方法去配置扫描接口,RequestHandlerSelectors配置如何扫描接口.apis(RequestHandlerSelectors.basePackage(com.kuang.swagger.controller))// 配置如何通过path过滤,即这里只扫描请求以/kuang开头的接口.paths(PathSelectors.ant(/kuang/**)).build();
}5、这里的可选值还有
any() // 任何请求都扫描
none() // 任何请求都不扫描
regex(final String pathRegex) // 通过正则表达式控制
ant(final String antPattern) // 通过ant()控制五、配置Swagger开关
1、通过enable()方法配置是否启用swagger如果是falseswagger将不能在浏览器中访问了
Bean
public Docket docket() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).enable(false) //配置是否启用Swagger如果是false在浏览器将无法访问.select()// 通过.select()方法去配置扫描接口,RequestHandlerSelectors配置如何扫描接口.apis(RequestHandlerSelectors.basePackage(com.kuang.swagger.controller))// 配置如何通过path过滤,即这里只扫描请求以/kuang开头的接口.paths(PathSelectors.ant(/kuang/**)).build();
}2、如何动态配置当项目处于test、dev环境时显示swagger处于prod时不显示
Bean
public Docket docket(Environment environment) {// 设置要显示swagger的环境Profiles of Profiles.of(dev, test);// 判断当前是否处于该环境// 通过 enable() 接收此参数判断是否要显示boolean b environment.acceptsProfiles(of);return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).enable(b) //配置是否启用Swagger如果是false在浏览器将无法访问.select()// 通过.select()方法去配置扫描接口,RequestHandlerSelectors配置如何扫描接口.apis(RequestHandlerSelectors.basePackage(com.kuang.swagger.controller))// 配置如何通过path过滤,即这里只扫描请求以/kuang开头的接口.paths(PathSelectors.ant(/kuang/**)).build();
}3、可以在项目中增加一个dev的配置文件查看效果
六、配置API分组
1、如果没有配置分组默认是default。通过groupName()方法即可配置分组
Bean
public Docket docket(Environment environment) {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).groupName(hello) // 配置分组// 省略配置....
}2、重启项目查看分组
3、如何配置多个分组配置多个分组只需要配置多个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);
}4、重启项目查看即可
七、实体配置
1、新建一个实体类
ApiModel(用户实体)
public class User {ApiModelProperty(用户名)public String username;ApiModelProperty(密码)public String password;
}2、只要这个实体在请求接口的返回值上即使是泛型都能映射到实体项中
RequestMapping(/getUser)
public User getUser(){return new User();
}3、重启查看测试
注并不是因为ApiModel这个注解让实体显示在这里了而是只要出现在接口方法的返回值上的实体都会显示在这里而ApiModel和ApiModelProperty这两个注解只是为实体添加注释的。
ApiModel为类添加注释
ApiModelProperty为类属性添加注释
八、常用注解
Swagger的所有注解定义在io.swagger.annotations包下
下面列一些经常用到的未列举出来的可以另行查阅说明
Swagger注解简单说明Api(tags “xxx模块说明”)作用在模块类上ApiOperation(“xxx接口说明”)作用在接口方法上ApiModel(“xxxPOJO说明”)作用在模型类上如VO、BOApiModelProperty(value “xxx属性说明”,hidden true)作用在类方法和属性上hidden设置为true可以隐藏该属性ApiParam(“xxx参数说明”)作用在参数、方法和字段上类似ApiModelProperty
我们也可以给请求的接口配置一些注释
ApiOperation(哥的时代的接口)
PostMapping(/gedeshidai)
ResponseBody
public String gedeshidai(ApiParam(这个名字会被返回)String username){return username;
}这样的话可以给一些比较难理解的属性或者接口增加一些配置信息让人更容易阅读
相较于传统的Postman或Curl方式测试接口使用swagger简直就是傻瓜式操作不需要额外说明文档(写得好本身就是文档)而且更不容易出错只需要录入数据然后点击Execute如果再配合自动化框架可以说基本就不需要人为操作了。
Swagger是个优秀的工具现在国内已经有很多的中小型互联网公司都在使用它相较于传统的要先出Word接口文档再测试的方式显然这样也更符合现在的快速迭代开发行情。当然了提醒下大家在正式环境要记得关闭Swagger一来出于安全考虑二来也可以节省运行时内存。
