Swagger
一、是什么?
1、简介
Swagger 是一个规范且完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。
简单理解就是两个作用
- 用于生成API文档的一个框架
- 还能进行在线测试
关联:
- 官网:https://swagger.io/
2、工具组件
有很多,记住一个核心常用组件
- Swagger UI:会读取代码中的注释,生成API文档网页
二、优势
- 支持 API 自动生成同步的在线文档:使用 Swagger 后可以直接通过代码生成文档,不再需要自己手动编写接口文档了,对程序员来说非常方便,可以节约写文档的时间去学习新技术。
- API文档也支持权限验证(观察者需要输入密码
- 不同的接口也有颜色分类(比如删除接口可以用红色
- 提供 Web 页面在线测试 API:光有文档还不够,Swagger 生成的文档还支持在线测试。参数和格式都定好了,直接在界面上输入参数对应的值即可在线测试接口。
三、 文档界面的用法
1、支持很完整的备注
2、支持接口测试
可以测试响应的内容
四、springfox
功能和Swagger一样,也是可以根据代码生成接口文档,只需要正常的进行更新项目版本、修改代码即可、不需要收到修改描述文件
利用自身AOP的特性,集成了Swagger,低层还是Swagger,但是使用起来很方便。
在实际开发中,使用spring-fox + swagger
具体用法
一、极速上手
-
进入mvnrepository.com搜索对应的依赖[SpringFox Swagger2]
-
使用2.92版本的依赖
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency>
-
导入另一个依赖[SpringFox Swagger UI]
-
也是2.92版本
<!-- 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>
-
在springboot启动类上方加入注解
@EnableSwagger2
。即可启动测试- 是Springfox提供的一个注解,代表swagger2相关技术的启动
- 会扫描启动类包及子包下所有类型的注解。做swagger文档的定值。
-
进入对应的地址即可访问
http://localhost:端口号/swagger-ui.html
-
可以发现在没有写任何注解情况下,spirngfox已经自动帮我们识别了之前写好的controller。如下
-
网址预览
测试问题:这里出现一个bug提示
提示内容:Failed to start bean ‘documentationPluginsBootstrapper’
解决方法参考[http://t.csdn.cn/OHYMY],原因就是是springboot的版本更新,导致的swagger2的异常
目前采用博客的第一个方法即解决——
-
在yml中新增配置
spring: mvc: pathmatch: matching-strategy: ant_path_matcher
补充知识点。Springmvc对不同请求的分类
之前我们使用的请求方式,都是使用注解@RequestMapping
。但是它只是其中一种请求方式,
@RequestMapping
属于“无限制请求”@PostMapping
——“POST请求”@GetMapping
——“get请求”
因为发现swagger也会识别这个请求类型做出不同的API文档,所以补充一下这个小知识点
二、具体配置用法(Swagger UI
在极速上手演示的,不难发现,默认Swagger就会读取一些springmvc的注解进行生成。如果有对应的约束(如POST/GET),就会有变化。
1、 配置文档的标题内容
-
创建一个配置类(创建config包下,新建类如下
package com.cykj.demo.config; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import springfox.documentation.builders.ApiInfoBuilder; import springfox.documentation.service.ApiInfo; import springfox.documentation.service.Contact; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; @Configuration public class SwaggerConfiguration { /* 创建了Docket类型的对象,并使用spring容器管理 是swagger的全局配置 */ @Bean public Docket docket(){ // 选择swagger版本 Docket docket = new Docket(DocumentationType.SWAGGER_2); ApiInfo apiInfo = new ApiInfoBuilder() .contact( // 配置swagger文档的主体 new Contact("发布者:朱华聪", // 发布者信息 "http://www.ta.com", // 发布者的企业网址 "[email protected]") // 发布者的电子邮件 ) .title("商品管理Swagger帮助文档测试") .description("描述测试描述测试描述测试描述测试描述测试描述测试") .version("1.3") .build(); docket.apiInfo(apiInfo); return docket; } }
-
如上配置后,效果如下图
2、扫描包配置
在原有的配置类内再加如下语句:
// 配置要扫描包的位置,默认是启动类所在包及所有子包
docket.select()
// 配置要扫描的包,包括其子包
.apis(RequestHandlerSelectors.basePackage("com.cykj.demo.controller"));
在此基础上,教程还讲解了使用自定义注解,跳过某些方法
三、Swagger2内置的常用注解
1、@Api
:描述类
描述当前类型生成帮助文档的信息
-
tags
—— 定义这个类的别名,可以使用大括号加逗号隔开的方式写多个别名举个例子
@RequestMapping @Api(tags = { "用户管理接口1","用户管理的接口别名~~"}) public class UserController {
效果如下
-
—— 描述信息,但是已经过时了description
2、@ApiOperation
——描述方法
value
——必须的,这个方法的别名notes
——一些细节描述
举个例子
@ApiOperation(value = "登陆接口",notes = "我是描述我是描述我是描述我是描述我是描述我是描述")
public ResponseVo login(String user , String pwd){
效果如下
3、@ApiParam
主要描述方法参数
name
——别名value
——具体描述required
—— 是否是必须的**(默认为false**
举个例子
public ResponseVo login(
@ApiParam(name = "用户名",value = "必须要输入的",required = true) String user ,
@ApiParam(name = "密码",value = "假设不必须") String pwd){
效果如下
4、@ApiIgnore 注解后不生成文档
顾名思义,添加后这个类/方法/属性不会再帮助文档里出现
5、@ApiImplicitParam
注解方法参数
和@apiparam
的作用一样,不同的是这个注解是加在方法上面的
参数一样是name是别名,value是描述,也有required是否必须,三种参数组成
-
而且警告测试,两个注解不能共存,会出现如下bug
6、@ApiModel
描述数据类型
专门对实体类进行描述,这个实体类型,如果成为某个方法的返回值类型时,此注解将被解析。
举个例子
@ApiModel(value = "响应载体" , description = "用于响应用于响应用于响应用于响应")
public class ResponseVo {
@ApiModelProperty(value = "表示状态" , name = "状态码" ,example = "200",required = true)
private int code; // 状态码
@ApiModelProperty(value = "表示信息" , name = "提示信息" ,example = "success")
private String message; // 提示信息
@ApiModelProperty(value = "存储数据" , name = "数据" ,example = "[m,n,b]")
private Object data; //数据
效果如下:
拉到最下方打开models可以看到